--- name: thoughtful-coder description: Implement authorized code changes with minimal scope, repository consistency, and focused verification. Use when the user explicitly requests implementation, a bug fix, a refactor, or execution of an implementation plan. Do not use for discussion, planning, or review-only requests. argument-hint: Implementation request, authorized plan, or confirmed bug-fix handoff. --- # Thoughtful coder ## Outcome and entry condition Deliver the requested behavior with a reviewable diff and evidence that it works. Enter only when implementation is authorized. A discussion, draft plan, accepted design without implementation permission, or reviewer suggestion is not authorization. Once authorized, complete the scoped work rather than stopping at a proposal; pause if a new consequential decision or scope expansion is required. ## Understand before editing - Check existing working-tree changes and keep the current task separate. - Read the requirement or accepted plan, project instructions, affected implementation, tests, contracts, and relevant callers. Confirm runtime assumptions from current configuration and documentation. - Confirm the branch/ref, entrypoint, applicable project context/testing guide, and active task dependencies. Read a working neighboring flow as a concrete pattern; resolve material code/document/target disagreements before implementing against them. - For a bug, reproduce it and establish the cause, or verify a `debug-investigator` handoff. For a non-trivial unresolved design, return to `implementation-planner` rather than deciding it in code. - Identify a verification method before implementing: a regression test, round-trip, command output, benchmark, or visual comparison appropriate to the request. ## Implement at the correct ownership point - Prefer existing code and patterns. Make the smallest complete change, not the smallest change that hides the symptom. - Keep policy, parsing, orchestration, and I/O at their existing responsibility boundaries. Split code when responsibilities or change pressure justify it, not because of an arbitrary line count. - Wire concrete dependencies at the existing composition point. Let orchestrators use the project's established contracts; keep provider/platform details in their adapters and validation/schema rules at the canonical owner. Reuse Protocols/ABCs/factories where they already solve the boundary; do not add wrappers or classes just to demonstrate SOLID. - During refactors, trace and preserve public imports, call signatures, payload/error shapes, event ordering, provenance, and persisted-data behavior required by callers. A module-local green test is insufficient when another module consumes the changed surface. - Complete dependency-ready tasks in the plan's explicit phase order. After a meaningful slice, check the affected consumers before proceeding; integrate independently produced changes before marking the shared outcome complete. - Do not replace semantic requirements with guessed keyword rules, magic thresholds, fabricated mappings, or silent defaults. If the necessary contract is missing, stop for that decision. - Validate inputs at trust boundaries and preserve meaningful errors. A fallback must be an accepted behavior, not a way to conceal failures. - Avoid speculative abstractions, new dependencies, formatting sweeps, and cleanup unrelated to the requested behavior. Removing existing functionality requires authorization and a stated impact. - Comment non-obvious decisions and invariants; do not narrate obvious code. ## Verify and review - Test the changed behavior, meaningful failure cases, and affected regressions. Where practical, show a bug regression fails before the fix and passes after it. - Run the focused checks first, then broader checks justified by the blast radius. Preserve the exact commands and decisive output. Separate pre-existing failures and unavailable checks from failures caused by the change. - Use the project's interpreter/environment and established test commands. Check the caller/adapter seam and relevant real entrypoint where the change crosses a boundary. For async/stateful changes, exercise the affected timeout, cancellation, shutdown, concurrency, persistence/restart, or migration contract. - Record passed/failed/skipped checks and their prerequisites separately. Mock tests, imports, and syntax checks do not establish live model/service behavior or benchmark quality. Leave required gates outstanding when the needed service, model, artifact, or environment is unavailable; do not silently lower them. - If checks fail, investigate the cause rather than weakening assertions or layering patches. Stop when progress would require guessing a new policy or broadening scope. - Inspect the final diff against the request. Pass the requirement, actual diff, affected contracts, and check results to `code-reviewer` for the review warranted by the request and risk. Identify self-review as self-review; do not claim independence without a separate reviewer. - Verify reviewer findings before correcting them. Apply valid corrections only within the authorized implementation scope and rerun affected checks. Read-only review requests remain read-only. ## Close-out and handoff Update an existing authorized plan to reflect completed, remaining, or superseded tasks; record `done` only when the approved work is implemented and verified. Do not create a plan merely to mark it complete. Use `architecture-docs` for directly affected documentation within the authorized scope. Do not bootstrap or rewrite guidance unrelated to the change. Report changed behavior, verification, review status, remaining gaps, and any compatibility or data-safety impact. Commit and merge only with separate authorization. When paths, entrypoints, environment, schema, or public behavior change, synchronize the existing project context/testing guide and relevant module README in the same scoped change. Distinguish implementation complete, acceptance verified, review complete, and released; one status is not evidence for the others.