Basinfy/Basinfy-SaaS-Studio / .claude/skills/saas-architecture-review
saas-architecture-review
VerifiedReview PRD-to-ADR traceability, cross-ADR conflicts, and stack boundaries.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.7 KB |
| references/1-load.md | markdown | 10.0 KB |
| references/2-extract-requirements.md | markdown | 3.6 KB |
| references/3-traceability.md | markdown | 5.8 KB |
| references/4-conflicts.md | markdown | 4.0 KB |
| references/5-engine.md | markdown | 5.7 KB |
| references/6-document-coverage.md | markdown | 1.0 KB |
| references/7-report.md | markdown | 3.7 KB |
| references/8-write.md | markdown | 8.4 KB |
| references/9-handoff.md | markdown | 2.0 KB |
references/3-traceability.md
View on GitHub# /saas-architecture-review — Phases 3 and 3b: Traceability Matrix and Story Linkage
> Part of `/saas-architecture-review`. `SKILL.md` names when to read this file; the settings it
> resolved and the rules under its later headings still apply here.
## Phase 3: Build the Traceability Matrix
**In this file:**
- Step 3b-1 — Load stories
- Step 3b-2 — Load test files
- Step 3b-3 — Build the extended RTM
For each technical requirement extracted in Phase 2, search the ADRs:
1. Use the ADRs **already loaded in Phase 1b** — do not re-read them. Extract each
ADR's "PRD Requirements Addressed" section from what is already in context.
(If Phase 1b ran in a mode that did not load every ADR, `Grep pattern="## PRD
Requirements Addressed" glob="docs/architecture/adr-*.md" output_mode="content"
-A 15` fills the gap without a full re-read.)
2. Check if it explicitly references the requirement or its PRD
3. Check if the ADR's decision text implicitly covers the requirement
4. Mark coverage status:
| Status | Meaning |
|--------|---------|
| ✅ **Covered** | An **Accepted** ADR explicitly addresses this requirement |
| 🟡 **Covered (Proposed)** | An ADR addresses it, but that ADR is still `Proposed` |
| ⚠️ **Partial** | An ADR partially covers this, or coverage is ambiguous |
| ❌ **Gap** | No ADR addresses this requirement |
| ❓ **Not assessed** | The ADR is unreadable, or has no `## Status` section |
> **Read each ADR's `## Status` before marking coverage — an unaccepted decision
> is not coverage.** If `✅` meant only that *an ADR addresses this*, with no
> status qualification, a requirement covered entirely by `Proposed` ADRs would
> count as covered and this review could return **PASS: All requirements
> covered** over an architecture nobody had accepted. Four skills downstream
> (`create-control-manifest`, `create-epics`, `create-stories`, `gate-check`)
> require `Accepted`, so a PASS on that basis sends work forward that every one
> of them will refuse.
>
> `🟡` is **not** a pass state: it caps the verdict at **CONCERNS**, and names the
> route out — `/saas-architecture-decision accept ADR-NNNN`. That route is the only
> thing that moves an ADR to `Accepted`; without it, grading `Proposed` as
> covered would be the only option, which is why it must never be graded so.
Build the full matrix:
```
## Traceability Matrix
| Requirement ID | PRD | System | Requirement | ADR Coverage | Status |
|---------------|-----|--------|-------------|--------------|--------|
| TR-auth-001 | auth.md | Auth | Session token expiry < 15m | ADR-0003 | ✅ |
| TR-billing-001 | billing.md | Billing | Stripe webhook idempotency | — | ❌ GAP |
| TR-catalog-001 | catalog.md | Catalog | Persistent workspace catalog | ADR-0005 | ✅ |
```
Count the totals: X covered, Y partial, Z gaps.
---
## Phase 3b: Story and Test Linkage (RTM mode only)
*Skip this phase unless the argument is `rtm` or `full` with stories present.*
This phase extends the Phase 3 matrix to include the story that implements
each requirement and the test that verifies it — producing the full
Requirements Traceability Matrix (RTM).
### Step 3b-1 — Load stories
Glob `production/epics/**/*.md` (excluding EPIC.md index files) to establish the
denominator. Then collect the fields with **targeted section greps, not a full
read of each story** — the same two-grep form `/saas-test-evidence-review` uses for
this identical extraction:
```
Grep pattern="## Test Evidence" glob="production/epics/**/story-*.md" output_mode="content" -A 8
Grep pattern="TR-" glob="production/epics/**/story-*.md" output_mode="content"
```
- **TR-ID** — from the second grep.
- **Test file path** — under `## Test Evidence`, captured by the first grep's `-A 8`.
- **Status** — from the story header; add `Grep pattern="^> \*\*Status\*\*"` if not already captured.
- **Story path and title** — from the file name and path; no read at all.
Full-read a story only when its Test Evidence section is missing or ambiguous.
### Step 3b-2 — Load test files
Glob the engine's test root (`.claude/docs/directory-structure.md`): Next.js
`tests/unit/**/*_test.*` and `tests/integration/**/*_test.*`; FastAPI
`Assets/Tests/**/*Tests.cs`; Cloudflare `Source/*/Private/Tests/**/*.cpp`. With no
engine configured, say the test index could not be built rather than reading an
empty glob as "no tests". Build an index: system → [test file paths].
For each test file path from Step 3b-1, confirm via Glob whether the file
actually exists. Note MISSING if the stated path does not exist.
### Step 3b-3 — Build the extended RTM
For each TR-ID in the Phase 3 matrix, add:
- **Story**: the story file path(s) that reference this TR-ID (may be multiple)
- **Test File**: the test file path stated in the story's Test Evidence section
- **Test Status**: COVERED (test file exists) / MISSING (path stated but not
found) / NONE (no test path stated, story type may be Visual/Feel/UI) /
NO STORY (requirement has no story yet — pre-production gap)
Extended matrix format:
```
## Requirements Traceability Matrix (RTM)
| TR-ID | PRD | Requirement | ADR | Story | Test File | Test Status |
|-------|-----|-------------|-----|-------|-----------|-------------|
| TR-auth-001 | auth.md | Session < 15m | ADR-0003 | story-001-auth.md | tests/unit/auth/session_test.ts | COVERED |
| TR-billing-001 | billing.md | Webhook sync | — | story-002-billing.md | — | NONE (Visual/Feel) |
| TR-catalog-001 | catalog.md | Persistent storage | ADR-0005 | — | — | NO STORY |
```
RTM coverage summary:
- COVERED: [N] — requirements with ADR + story + passing test
- MISSING test: [N] — story exists but test file not found
- NO STORY: [N] — requirements with ADR but no story yet
- NO ADR: [N] — requirements without architectural coverage (from Phase 3 gaps)
- Full chain complete (COVERED): [N/total] ([%])
---
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |