# Skill Test Spec: /architecture-decision ## Skill Summary `/architecture-decision` guides the user through section-by-section authoring of a new Architecture Decision Record (ADR). Required sections are: Status, Context, Decision, Consequences, Alternatives, and Related ADRs. The skill also stamps the engine version reference from `docs/engine-reference/` into the ADR for traceability. In `full` review mode, TD-ADR (technical-director) and LP-FEASIBILITY (lead-programmer) gate agents spawn after the draft is complete. If both gates return APPROVED, the ADR status is set to Accepted. In `lean` or `solo` mode, both gates are skipped and the ADR is written with Status: Proposed. The skill asks "May I write" per section during authoring. ADRs are written to `docs/architecture/adr-NNN-[name].md`. --- ## Static Assertions (Structural) Verified automatically by `/skill-test static` — no fixture needed. - [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools` - [ ] Has ≥2 phase headings - [ ] Contains verdict keywords: ACCEPTED, PROPOSED, CONCERNS - [ ] Contains "May I write" collaborative protocol language (per-section approval) - [ ] Has a next-step handoff at the end - [ ] Documents gate behavior: TD-ADR + LP-FEASIBILITY in full mode; skipped in lean/solo - [ ] Documents that ADR status is Accepted (full, gates approve) or Proposed (otherwise) - [ ] Mentions engine version stamp from `docs/engine-reference/` --- ## Director Gate Checks In `full` mode: TD-ADR (technical-director) and LP-FEASIBILITY (lead-programmer) spawn after the ADR draft is complete. If both return APPROVED, ADR Status is set to Accepted. If either returns CONCERNS or FAIL, ADR stays Proposed. In `lean` mode: both gates are skipped. ADR is written with Status: Proposed. Output notes: "TD-ADR skipped — lean mode" and "LP-FEASIBILITY skipped — lean mode". In `solo` mode: both gates are skipped. ADR is written with Status: Proposed. --- ## Test Cases ### Case 1: Happy Path — New ADR for rendering approach, full mode, gates approve **Fixture:** - `docs/architecture/` exists with no existing ADR for rendering - `docs/engine-reference/[engine]/VERSION.md` exists - `production/session-state/review-mode.txt` contains `full` **Input:** `/architecture-decision rendering-approach` **Expected behavior:** 1. Skill guides user through each required section (Status, Context, Decision, Consequences, Alternatives, Related ADRs) 2. Engine version is stamped into the ADR from `docs/engine-reference/` 3. For each section: draft shown, "May I write this section?" asked, approved 4. After all sections: TD-ADR and LP-FEASIBILITY gates spawn in parallel 5. Both gates return APPROVED 6. ADR Status is set to Accepted 7. Skill writes `docs/architecture/adr-NNN-rendering-approach.md` 8. `docs/architecture/tr-registry.yaml` updated if new TR-IDs are defined **Assertions:** - [ ] All 6 required sections are authored and written - [ ] Engine version reference is stamped in the ADR - [ ] TD-ADR and LP-FEASIBILITY spawn in parallel (not sequentially) - [ ] ADR Status is Accepted when both gates return APPROVED in full mode - [ ] "May I write" is asked per section during authoring - [ ] File is written to `docs/architecture/adr-NNN-[name].md` --- ### Case 2: Failure Path — TD-ADR returns CONCERNS **Fixture:** - ADR draft is complete (all sections filled) - `production/session-state/review-mode.txt` contains `full` - TD-ADR gate returns CONCERNS: "The decision does not address [specific concern]" **Input:** `/architecture-decision [topic]` **Expected behavior:** 1. TD-ADR gate spawns and returns CONCERNS with specific feedback 2. Skill surfaces the concerns to the user 3. ADR Status remains Proposed (not Accepted) 4. User is asked: revise the decision to address concerns, or accept as Proposed 5. ADR is written with Status: Proposed if concerns are not resolved **Assertions:** - [ ] TD-ADR concerns are shown to the user verbatim - [ ] ADR Status is Proposed (not Accepted) when TD-ADR returns CONCERNS - [ ] Skill does NOT set Status: Accepted while CONCERNS are unresolved - [ ] User is given the option to revise and re-run the gate --- ### Case 3: Lean Mode — Both gates skipped; ADR written as Proposed **Fixture:** - `production/session-state/review-mode.txt` contains `lean` - ADR draft is authored for a new technical decision **Input:** `/architecture-decision [topic]` **Expected behavior:** 1. Skill guides user through all 6 sections 2. After draft is complete: both TD-ADR and LP-FEASIBILITY are skipped 3. Output notes: "TD-ADR skipped — lean mode" and "LP-FEASIBILITY skipped — lean mode" 4. ADR is written with Status: Proposed (not Accepted, since gates did not approve) 5. "May I write" is still asked before the final file write **Assertions:** - [ ] Both gate skip notes appear in output - [ ] ADR Status is Proposed (not Accepted) in lean mode - [ ] "May I write" is still asked before writing the file - [ ] Skill writes the ADR after user approval --- ### Case 4: Edge Case — ADR already exists for this topic **Fixture:** - `docs/architecture/` contains an existing ADR covering the same topic - The existing ADR has Status: Accepted **Input:** `/architecture-decision [same-topic]` **Expected behavior:** 1. Skill detects an existing ADR covering the same topic 2. Skill asks: "An ADR for [topic] already exists ([filename]). Update it, or create a new superseding ADR?" 3. User selects update or supersede 4. Skill does NOT silently create a duplicate ADR **Assertions:** - [ ] Skill detects the existing ADR before authoring begins - [ ] User is offered update or supersede options — no silent duplicate - [ ] If update: skill opens the existing ADR for section-by-section revision - [ ] If supersede: new ADR references the superseded one in Related ADRs section --- ### Case 5: Director Gate — Status set correctly based on mode and gate outcome **Fixture:** - ADR draft is complete - Two scenarios: (a) full mode, both gates APPROVED; (b) full mode, one gate CONCERNS **Full mode, both APPROVED:** - ADR Status is set to Accepted **Assertions (both approved):** - [ ] ADR frontmatter/header shows `Status: Accepted` - [ ] Both TD-ADR and LP-FEASIBILITY appear as APPROVED in output **Full mode, one gate returns CONCERNS:** - ADR Status stays Proposed **Assertions (CONCERNS):** - [ ] ADR frontmatter/header shows `Status: Proposed` - [ ] Concerns are listed in output - [ ] Skill does NOT set Status: Accepted when any gate returns CONCERNS **Lean/solo mode:** - ADR Status is always Proposed regardless of content quality **Assertions (lean/solo):** - [ ] ADR Status is Proposed in lean mode - [ ] ADR Status is Proposed in solo mode - [ ] No gate output appears in lean or solo mode --- ## Protocol Compliance - [ ] All 6 required sections authored before gate review - [ ] Engine version stamped in ADR from `docs/engine-reference/` - [ ] "May I write" asked per section during authoring - [ ] TD-ADR and LP-FEASIBILITY spawn in parallel in full mode - [ ] Skipped gates noted by name and mode in lean/solo output - [ ] ADR Status: Accepted only when full mode AND both gates APPROVED - [ ] Ends with next-step handoff: `/architecture-review` or `/create-control-manifest` --- ## Coverage Notes - ADR numbering (auto-incrementing NNN) is not independently fixture-tested — the skill reads existing ADR filenames to assign the next number. - Related ADRs section linking (supersedes / related-to) is tested structurally via Case 4 but not all link types are individually verified. - The TR-registry update (when new TR-IDs are defined in the ADR) is part of the write phase — tested implicitly via Case 1.