Write the Spec First, Then Build in Small Test-First Steps

## Log Unclear Requirements as Questions and Wait for Answers Before Planning Do not plan or implement while a material requirement is unclear. Identify unresolved requirements, nonfunctional expectations, behavior, telemetry, policy, and acceptance criteria before proposing changes. Record every high-impact clarification and each medium-impact uncertainty in the repository's designated open-question register before asking for a decision. Give each question a stable identifier and keep the governing specification, plan, and task list scoped to that identifier until it is resolved. When presenting alternatives, store the same options first, then summarize them directly for the user. Rank the recommended option first, provide concise pros and cons, cite the question identifier, and stop until the required answer is available. Once resolved, fold the answer into the specification's normative sections and close the register entry. ## Read the Spec and Architecture Map Before Planning Work from the repository root and apply repository-wide instructions plus every relevant nested rule. Before planning, read the current roadmap, governing feature specification, module or knowledge map, coding conventions, and architectural decisions linked to the affected feature. Map the modules, contracts, and ownership boundaries the change can affect. Use the repository's maintained architecture snapshot rather than inferring relationships from a nearby file alone, and update that map when modules, dependencies, or contracts change. Use approved templates for specifications, plans, tasks, and architectural decisions so metadata, verification notes, and cross-links remain consistent. ## Update the Spec First, Then the Plan and Task List Create or refresh the feature specification before implementation. Define requirements, nonfunctional requirements, behavior or interface details, telemetry and policy, acceptance branches, and an interface sketch when visual behavior changes. Resolve all high- and medium-impact questions before generating the implementation plan. Record architecturally significant outcomes in an architectural decision record after updating the specification, and keep resolved clarifications in normative sections rather than a separate legacy clarification list. Only then refresh the plan and task checklist. Order tests before implementation, divide work into logical increments expected to fit within 90 minutes, and run the repository's analysis gate after the specification, plan, and tasks agree. Do not invent fallback or compatibility behavior unless the user explicitly requests it. ## Resume the Session From One Saved Snapshot and Update It Before Handoff At the start of a context-free session, follow the repository's reset or handoff runbook. Summarize roadmap status, active plan progress, and unresolved questions before taking new implementation work. Maintain one designated current-session snapshot as the live cross-session state. Update it before handoff with the active feature, completed work, pending questions, verification state, and next safe action. Do not create competing progress records. Keep feature and module ownership explicit so documentation, automation, security, persistence, and interface work are updated in their governing locations. ## Write a Failing Test First for Each Behavior Update the governing specification and plan before changing code. For each behavior, write or extend an executable unit, behavior, contract, or scenario test first and confirm that it fails for the intended reason. List success, validation, and failure branches during planning and add a thin failing test for each path. Implement only enough code to make the tests pass, then refactor while keeping them green. After the loop closes, record coverage changes, lessons, and follow-up work in the plan or roadmap so the reasoning remains auditable. ## Make Small, Self-Contained Changes and Mark Tasks Done Right Away Keep each increment self-contained and follow the repository's language, framework, documentation, and test conventions. Prefer straight-line orchestration composed from small validation and normalization helpers over deeply nested inline branching. Synchronize the roadmap, specification, plan, and task checklist as behavior changes. Mark each verified task complete immediately rather than batching status updates, and update the architecture map whenever a module relationship or contract changes. Use decision records only for confirmed architectural decisions. Avoid unrelated refactoring, mass formatting, or speculative compatibility work, and keep the implementation aligned with the approved increment. ## Run Checks for the Changed File Types and Investigate Failures Instead of Skipping Them Run the narrowest applicable formatter, linter, static analysis, type check, and focused tests while iterating. Before completion, run every repository-required gate for the modified file types and any directly affected integration boundary. Treat a failing local or continuous-integration check as a defect to investigate, not a gate to bypass. If repository policy explicitly permits a temporary test waiver, disable only the affected test, add a clear TODO and reason, and record the follow-up in the governing plan. Add or update tests for every changed behavior. Review the final diff, confirm documentation and test coverage match the implementation, and do not declare the increment complete while required checks remain failing. ## Ask Before Adding Dependencies or Running Risky Git Steps Stage only files that belong to the increment. Do not use broad staging when generated output, database artifacts, or parallel work may exist. Prepare an atomic conventional commit description, including specification impact when documentation and code change together, but let the designated operator commit unless execution has been explicitly delegated. Obtain explicit approval before adding or upgrading dependencies, deleting exact files or directories, rewriting history, pushing, or creating an external review. Record an approved dependency's rationale in the feature plan and allow enough time for managed hooks and quality pipelines. Never commit secrets or use destructive cleanup as a shortcut. Surface unexpected tracked or untracked files for review and leave unrelated work untouched. ## Skip Compatibility Fallbacks Unless Asked and Propose Risky Changes First Follow the repository's declared compatibility stance. When interfaces are treated as greenfield, do not add fallbacks, shims, or legacy checks unless the user explicitly requests them for the current task. Record prompt summaries, material command sequences, and rationale in the active plan or a linked appendix. Propose risky refactors, persistence changes, security strategy changes, and major nonfunctional trade-offs before editing, then record approved architectural decisions in the proper decision log. Track future contract tests, mutation analysis, and security exercises in plans until automated gates exist. Keep operational guidance close to its authoritative workflow and avoid duplicating mutable instructions across documents. ## Run Tests Only on the Test Database and Confirm the Target Before Any Reset Never run a database reset, wipe, or fresh-migration command against an unverified connection. Before any migration or reset, confirm the active environment, connection target, and whether the operation is confined to a disposable test database. Run application tests against the repository's isolated test database and rely on its documented transaction or migration setup. Reset only the explicitly identified test database when necessary; do not assume a test command and an interactive application command share the same connection. Create new migrations as files and exercise them through the test workflow. If database scope is ambiguous, stop and obtain confirmation instead of risking development or production data. ## End Each Step With a Handoff of What Changed and What Was Checked After a self-contained increment passes its applicable gates, confirm completed tasks, roadmap status, specification changes, decision records, and the current-session snapshot are synchronized. Provide a compact handoff that lists changed files, checks run and their outcomes, unresolved blockers, follow-up work, and any copy-ready operator commands. Distinguish work that is implemented from work that is merely planned or awaiting authorization. Prepare the feature commit promptly after verification, but execute it only within the repository's delegation policy. Preserve enough evidence for the next session to resume without repeating discovery.