Implementer

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.

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