thoughtful-coder · diff
git:20260822.d70202a to git:20261001.f1e72be
27 added, 27 removed. Audit A to A.
---
name: thoughtful-coder
- description: Implement careful, surgical code changes with minimal scope, repository consistency, and focused verification.
- argument-hint: A coding task, bug, refactor, or feature to implement carefully.
+ 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.
---
- Use this skill to implement code changes. Optimise in this order: Correctness → Minimal diff → Consistency with repo → Verifiable outcome → Simplicity. Follow the shared work principles in `~/.claude/skills/AGENTS.md`; this file defines the coding-specific workflow.
-
- ## Before editing
+ # Thoughtful coder
- - If `.agents/` is missing, run `architecture-docs` first to bootstrap it.
- - Read project instructions and the code path being changed.
- - Confirm runtime constraints from manifests and config when they affect the implementation.
- - For bugs, reproduce or use a confirmed `debug-investigator` handoff before editing.
+ ## Outcome and entry condition
- ## Implementation
+ Deliver the requested behavior with a reviewable diff and evidence that it works.
- - Change the correct ownership point, not only the reported symptom path.
- - Match existing style, helpers, and module boundaries.
- - SOLID is hard: entity / I/O / policy / orchestrator in separate files — no shim, no collapse. A class stays under 300 lines including comments, docstrings, and blanks (~200 → re-check SRP). Split first if the next edit would cross 300. Generated/vendored exempt.
- - Clean only unused imports or artifacts introduced by the change.
- - Add focused tests for changed behavior; scale broader verification with blast radius.
- - Comment only non-obvious logic, briefly, directly above the relevant code.
+ 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.
- Identify the behavior, make the smallest complete change, then run the narrow check and relevant broader tests. Do not stop at a proposal unless the user asked for one.
+ ## Understand before editing
- ## Plan close-out
+ - 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.
+ - 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.
- If the task has an implementation plan, tick completed tasks with the date and update its status:
+ ## Implement at the correct ownership point
- - `done` - all approved work landed.
- - `in-progress` - approved tasks remain.
- - `abandoned` - superseded; record the reason.
+ - 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.
+ - 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.
- Do not leave a completed plan in `in-progress`.
+ ## Verify and review
- ## Documentation impact
+ - 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.
+ - 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.
- For non-trivial changes, report whether root `README.md`, `.agents/` docs, or a plan lifecycle changed. Defer broad documentation work to `architecture-docs`.
+ ## Close-out and handoff
- ## Output
+ 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.
- Lead with what changed and whether verification passed. Then state assumptions and unresolved risk only when they matter.
+ 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.