aTeering/skills

Engineer

Synthesize discovery into two durable artifacts: a spec that /implement can execute, and ADRs for decisions worth remembering.

Input: $ARGUMENTS.

Zero silent assumptions. Every design choice is either made by the user or listed as an assumption. That includes choices that feel too small to ask about (library, error format, naming, defaults, limits), what you infer from the codebase, and your own recommendations. Carry an Assumptions Ledger (✅ confirmed by user · ❓ unconfirmed · ❌ rejected) through the whole process, and never write an unconfirmed choice into a spec or ADR as a decision.

Process

1. Refine. If there is no Refined Brief yet in this session, run the /refine process first (grill → acceptance criteria). Don't proceed with open questions that block design. If a brief exists, carry its ❓ assumptions into your ledger; resolve them before designing anything that depends on them.
2. Model. Run the /domain-modelling process for any new or changed concepts and update the domain doc. The spec must use those canonical terms.
3. Explore the codebase. Identify the modules, interfaces, data stores, and tests the change touches. Note existing patterns to follow. Reference real paths. What the code does today is evidence, not intent: "follow the existing pattern in src/x.ts" is itself a choice to confirm with the user, logged with its source.
4. Design. For each significant decision, lay out 2–3 options with trade-offs and a recommendation; the user decides, and a recommendation only counts once they explicitly pick it. For smaller choices, batch them into one confirmation list rather than deciding them yourself. Consider data model & migrations, API/contract changes, error handling, security, performance, observability, rollout & rollback, and backwards compatibility.
5. Record ADRs. A decision deserves an ADR if it is hard to reverse, affects multiple modules, or a future engineer would ask "why did we do it this way?". Write each to docs/adr/NNNN-kebab-title.md (next free number, 4 digits) using adr-template.md. If an ADR supersedes another, update the old one's status. Mark an ADR Accepted only when the user confirmed the decision; otherwise it stays Proposed.
6. Write the spec to docs/specs/<kebab-title>.md using spec-template.md. Break work into small, ordered, independently testable tasks — each with the test(s) that prove it. Fill the spec's Assumptions section from the ledger; every design statement must trace to a user decision or appear there as ❓.
7. Review with the user. Summarize the spec and ADRs, show the open ❓ items, ask for sign-off, and adjust. Don't set the spec to Approved while any ❓ affects a task, acceptance criterion, or ADR.

Rules

• Respect the project's existing conventions if it already has spec/ADR folders or templates — use those instead.
• The spec describes what and how to verify, with enough how to remove ambiguity — not a line-by-line implementation.
• Every acceptance criterion must map to at least one task and test.
• Keep it as short as the change allows.

Next step

Recommend /handoff (to start implementation in a fresh session) or /implement docs/specs/<file>.md directly.