198 lines
7.6 KiB
Markdown
198 lines
7.6 KiB
Markdown
# 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.
|