implementer

name	implementer
description	Implement an approved implementation plan step by step, producing small reviewable changes, mapping code/tests to acceptance criteria, and maintaining a lightweight decision log. Use when the plan/spec is already agreed and you want disciplined execution.

Implementer

Implement an approved implementation plan one step at a time, with tight traceability from plan → code → tests.

Primary goals:

1. Acceptance criteria satisfied
2. Small, reviewable diffs
3. Clear mapping: plan step → files → tests
4. Explicit decisions and uncertainty handling

---

Required Inputs (Do Not Start Without These)

1. The implementation plan or feature spec, including acceptance criteria
2. Repo standards (read what applies to touched files):
   • AGENTS.md
   • ui/AGENTS.md (if UI work is involved)
   • DOCUMENTATION_STRUCTURE.md
   • docs/architecture/ARCHITECTURE.md
   • docs/CODE-REVIEW.md

If the plan or acceptance criteria are missing, ask for them before doing any work.

---

Execution Rules

Rule 1: One step at a time

Work on exactly one plan step at a time. Do not start the next step until the current step is done and marked.

Rule 2: Status marking in the plan

When starting a step, mark it as ongoing. When finished, mark it as done (with a checkbox).

Use this format:

• Step N: Title
  • status: ongoing
  • notes: short summary of what is being done

Then update to:

• Step N: Title
  • status: done
  • notes: summary of what changed and where
  • tests: tests added/updated (or “n/a” with reason)
  • ac_coverage: which acceptance criteria this step supports

Rule 3: Minimal diff

Prefer the smallest change that is correct. Refactor only when it reduces risk, reduces future change cost, or unblocks correctness.

Rule 3b: No dynamic “maybe-method” hacks for internal contracts

Avoid patterns like getattr(obj, "method", None) / hasattr() / “if callable then call” for internal code paths that are part of the repo’s contracts.

• If the method/function “should always exist”, call it directly.
• If behavior is intentionally optional (plugin/provider boundary), detect capability once at the boundary and keep the rest of the code contract-driven.
• Telemetry/metrics must be best-effort: failures in tracking should never change prompts, retries, or request logic; they should degrade to “no metrics” with clear logs/tests.

Rule 3c: Prefer concrete types over catch-alls

If you're reaching for a catch-all type (any, Any, Object, dynamic, void*, Box<dyn Any>, untyped dict / list, etc.), stop and check whether a concrete type would work. If it genuinely wouldn't — boundary deserialization, true generic plumbing, gradual typing of legacy code — leave a one-line comment explaining why. Types and type checking drive quality; escape hatches are a deliberate choice, not a default. See the per-language table in .skills/code-reviewer/SKILL.md for what counts as a catch-all in each language.

Rule 4: Tests map to acceptance criteria

For each acceptance criterion, ensure at least one of:

• unit tests
• integration tests
• UI tests

Or explicitly record why automation is not appropriate.

For the main user-visible or workflow-critical acceptance criterion, coverage must exercise the exact reported workflow: the same mode, host/shell, file state, and interaction sequence. A nearby happy path is not sufficient proof. For browser + desktop-visible UI behavior, cover both the hosted browser path and the desktop adapter/native-open path, or record why one is out of scope.

For bug fixes, prefer failing-first evidence: run the new regression against the broken code when feasible, or document why that could not be done.

Rule 5: Stop on impactful uncertainty

Stop and ask a question if any of these are unclear:

• acceptance criteria meaning/scope
• API contract behavior or backward compatibility
• data model invariants or migrations
• security/permission behavior
• error semantics and retryability
• cross-system integration expectations

If the uncertainty is not impactful, choose the simplest interpretation and record it in the Decision Log with an ASSUMPTION tag so reviewers can validate it:

• Assumption: [what you assumed]
  • context: [what in the plan was ambiguous]
  • alternative: [what else you considered]

Rule 7: Ask before deviating from repo standards

Before using patterns that deviate from AGENTS.md or other repo standards, stop and ask for approval. Common examples requiring approval:

• Imports inside functions (only allowed for: optional deps with graceful fallback, breaking circular imports, or expensive modules in rarely-used paths)
• Non-standard error handling patterns
• New dependencies or frameworks
• Architecture boundary violations

Do not assume an exception applies—ask first, then document the approved exception in the Decision Log.

Rule 6: Record decisions (lightweight)

Maintain a Decision Log in the plan doc or PR description.

Make a decision entry when:

• there are multiple reasonable implementations
• user-visible behavior changes
• integrations/contracts could be affected
• tradeoffs were made that reviewers should know

Decision Log format:

• Decision: short title
  • context: why a decision was needed
  • options: 2–3 options considered
  • choice: what was chosen
  • rationale: why this choice
  • impact: what this affects
  • followups: planned cleanup/risks

Rule 8: Scope discipline

Before touching any file, confirm the change is within the approved scope. If you notice something that should be fixed but is out of scope:

1. Do NOT fix it
2. Record it using the NOTICED pattern in your Decision Log (Rule 6):

NOTICED: [file or issue]
DESCRIPTION: [what you saw]
RECOMMENDATION: [fix in follow-up quest / add to backlog]

This preserves the observation without polluting the current diff.

---

Implementation Process

Step 0: Plan and repo alignment check

Confirm:

• acceptance criteria are present and testable
• plan steps are actionable and sequenced
• repo boundaries and standards are understood

Step 1: Execute the current plan step

1. Mark the plan step as ongoing
2. Implement code changes for this step
3. Add/update tests for this step and its acceptance criteria
4. Update docs if required by DOCUMENTATION_STRUCTURE.md
5. Mark the plan step as done with brief notes/tests/ac coverage

Step 2: Self review before moving on

Before starting the next step, verify:

• architecture boundaries are respected (AGENTS.md, ui/AGENTS.md, ARCHITECTURE.md, UX_HIGH_LEVEL_IMPLEMENTATION_IDEA.md)
• error handling matches existing patterns
• tests are deterministic and meaningful
• no secrets/sensitive data are logged or returned
• changes are minimal and reviewable

---

Common Pitfalls

Shortcut	Why It Fails	Red Flag
"I'll add tests after I finish the logic"	Bugs compound — a bug in step 1 makes steps 2-5 wrong. Tests written after the fact test implementation, not behavior.	Code files growing without corresponding test files appearing
"Fixing one more thing while I'm here"	Diff grows, review slows, risk compounds. Mixed refactors and features make both harder to review and debug.	Commit message mentions unrelated cleanup