trace-requirements
Skill2 starsChanged 40 days agoMITView on GitHub
Verify every PRD functional requirement is implemented in the branch diff — map each FR (and each row of the acceptance-criteria contract, guards included) to code/spec evidence or flag it MISSING/PARTIAL
1 other project uses a version of this.
Adopted by
Most recently taken up by
- adolfoaranaes12/BMAD-ENHANCEDtheir own version, first seen Jan 28, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- adolfoaranaes12/BMAD-ENHANCED★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository75 other files it gives its agents.
- acceptance-criteriaSkill
- architect-guideSkill
- architect-reviewSkill
- audit-fixerSkill
- avo-admin-expertSkill
- backend-services-expertSkill
- bug-hunt-allSkill
- bug-hunt-fixSkill
- bug-huntSkill
- build-feature-remoteSkill
- build-featureSkill
- codeSkill
- component-testSkill
- controller-expertSkill
- create-qa-documentSkill
- debugSkill
- devops-expertSkill
- execute-qaSkill
- feature-qaSkill
- fix-bug-indexSkill
- fix-honeybadgerSkill
- fix-spec-bugsSkill
- fix-system-testSkill
- frontend-expertSkill
- frontend-reviewSkill
- full-qa-fixSkill
- full-qaSkill
- full-reviewSkill
- green-ciSkill
- group-issuesSkill
- honeybadger-auditSkill
- ideateSkill
- impact-assessmentSkill
- improveSkill
- merge-mainSkill
- model-expertSkill
- model-testSkill
- native-bug-hunt-fixSkill
- native-bug-huntSkill
- page-speedSkill
- plan-questionsSkill
- planSkill
- plan-system-testsSkill
- policy-testSkill
- prdSkill
- prd-worktreeSkill
- product-questionSkill
- product-question-tldrSkill
- qa-branchSkill
- qa-testerSkill
- refactor-sweepSkill
- resolve-honeybadgerSkill
- resolve-issueSkill
- resolve-issuesSkill
- review-acceptance-criteriaSkill
- review-fixesSkill
- review-railsSkill
- rspec-test-expertSkill
- scale-reviewSkill
- service-testSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 6 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 9
Verify that the current branch actually implements the PRD at "${1:blank}": map every Functional Requirement and Definition of Done item to …
- Very specific: line 23
If "${1}" is a path under .claude/acceptance-criteria/, read that contract, follow its *PRD:* link, and read that PRD.
- Very specific: line 25
If "${1}" is a PRD path, read it, then derive the slug (its *Feature slug:* header, else the filename) and look for …
- Very specific: line 27
If blank, resolve from the branch: git branch --show-current, strip the feature/ prefix, and look for .claude/prds/<slug>.md and …
- Very specific: line 32
If no PRD can be found, stop and say so — a trace without a PRD is meaningless.
- Very specific: line 34
If no contract file exists, continue: the ## Acceptance Criteria Trace (static) section reads N/A — no contract file.
- Very specific: line 68
If there is no Definition of Done section, report its trace as N/A — PRD has no Definition of Done and note the non-conformance under …
- Distinctive: line 81
If the diff is empty (you're on main, or the branch has no commits), stop and say so — there is nothing to trace against.
- Distinctive: line 84
Read the full diff (git diff main...HEAD), keeping a map of changed files by layer (migrations, models, services, controllers, policies, …
- Distinctive: line 99
Check spec coverage: which spec files in the diff exercise this requirement.
- Very specific: line 114
Do the analysis inline with Grep/Glob/Read — no sub-agents needed.
- Distinctive: line 224
Report-only: Never edit application code, specs, the PRD, or the contract — even for a one-line gap.
- Distinctive: line 226
Evidence over inference: Every IMPLEMENTED status cites files you actually read.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Requirements Traceability
Verify that the current branch actually implements the PRD at "${1:blank}": map every
Functional Requirement and Definition of Done item to concrete code/spec evidence in the
branch diff, or flag it as a gap. This skill analyzes and reports only — it never edits
code. Callers (a human, or the /build-feature pipeline) decide what to do with the gaps.
This is the static gate between "the reviews liked the plan" and "QA exercised the behavior": it catches requirements that were dropped between plan and code, which neither plan review nor QA-scenario execution is guaranteed to notice.
Phase 1: Resolve the PRD and the contract
"${1}" may be a PRD path or an acceptance-criteria contract path; the trace needs the PRD and uses the contract when one exists.
- If "${1}" is a path under
.claude/acceptance-criteria/, read that contract, follow its*PRD:*link, and read that PRD. - If "${1}" is a PRD path, read it, then derive the slug (its
*Feature slug:*header, else the filename) and look for.claude/acceptance-criteria/<slug>.md. - If blank, resolve from the branch:
git branch --show-current, strip thefeature/prefix, and look for.claude/prds/<slug>.mdand.claude/acceptance-criteria/<slug>.md. If the PRD misses, fall back to the newest PRD:ls -t .claude/prds/*.md 2>/dev/null | head -1— but verify its*Feature slug: \...`*` header plausibly matches the branch before trusting it. - If no PRD can be found, stop and say so — a trace without a PRD is meaningless. Suggest
/prdto create one. - If no contract file exists, continue: the
## Acceptance Criteria Trace (static)section readsN/A — no contract file; run /acceptance-criteria, and the verdict is unaffected.
Extract from the PRD:
- Functional Requirements — the
| ID | Requirement | Priority | Observable outcome |tables under## Functional Requirements(grouped under###category headings; IDs areFR-1,FR-2, … Priority isMustorShould; the Observable outcome is what the code must plausibly produce) - Definition of Done — the checkbox list under
## Definition of Done(lists the Must FRs) - Out of Scope — the numbered bullets (
OOS-1,OOS-2, …) under### Out of Scope — Do NOT Build - Edge Cases & Policies — the decided-behavior table (rows carry an
IDcolumn,EC-1,EC-2, …; used as supporting evidence targets)
Ignore any ## Acceptance Criteria section embedded in a PRD — the contract file is the only
source of ACs.
Extract from the contract (when present):
- Acceptance Criteria — the
## Contracttable (| ID | Type | Criterion | Source | Priority | Verified by |, rowsAC-1, …). Type isfeature,permission,edge, orguard; Source cites the PRD items (FR-n,OOS-n,EC-n,PERM-…,UX-…,DOD-n) the row proves. Note the*Review status:*line — anUNREVIEWED/FAILcontract is still traced, but say so under Ambiguities. - Guard rows (
Type = guard) assert an observable absence; they are traced in Phase 3 as scope-drift checks, not as things to implement.
Tolerate PRD format drift — older or hand-written PRDs deviate from the /prd template.
Handle gracefully rather than failing:
- FR IDs may be non-sequential or suffixed (
FR-7a) — trace whatever IDs exist - The FR table's fourth column may be named
Acceptance CriteriaorNotesinstead ofObservable outcome— read it the same way; if it is empty, the Requirement text itself is the criterion - Out-of-Scope bullets or Edge Case rows without IDs — number them in order (
OOS-n,EC-n) - The Out of Scope heading varies (
### Out of Scope (v1)etc.) — match on "Out of Scope" - If there is no Definition of Done section, report its trace as
N/A — PRD has no Definition of Doneand note the non-conformance under Ambiguities; do NOT invent items and do NOT let its absence affect the verdict (the verdict then rests on FRs alone)
Phase 2: Scope the Diff
git branch --show-current
git diff main...HEAD --stat
git diff main...HEAD --name-only
git log main..HEAD --onelineIf the diff is empty (you're on main, or the branch has no commits), stop and say so —
there is nothing to trace against.
Read the full diff (git diff main...HEAD), keeping a map of changed files by layer
(migrations, models, services, controllers, policies, components, views, Stimulus, jobs,
mailers, specs).
Phase 3: Trace Each Requirement
For every FR, every non-guard contract row (feature / permission / edge), and
every Definition of Done checkbox, in order:
- Locate candidate evidence in the diff: the files, methods, routes, components, and specs that would satisfy it.
- Read the implementing code — enough of it to confirm the acceptance criterion is plausibly satisfied at the code level. File names and method names alone are NOT evidence; a controller action that exists but ignores the required parameter is PARTIAL, not IMPLEMENTED. (Browser-level confirmation remains QA's job — this gate is static.)
- Check spec coverage: which spec files in the diff exercise this requirement.
Assign a status:
- IMPLEMENTED — code satisfies the acceptance criterion and has spec coverage
- PARTIAL — some of the requirement exists but a stated part of the acceptance criterion is absent (name exactly what's missing); or code is complete but has zero spec coverage (note that as the missing part)
- MISSING — no meaningful evidence in the diff
Client-side carve-out: the zero-spec-coverage → PARTIAL rule applies to Ruby code. For behavior that lives in Stimulus controllers / JS (this repo has no JS unit-test framework), IMPLEMENTED requires the controller code to satisfy the criterion and the markup wiring (targets/actions/values in a component or view, ideally asserted by a component spec) to be present — browser-level proof is QA's job. Note such FRs under Ambiguities so the caller knows they rest on static evidence only.
Do the analysis inline with Grep/Glob/Read — no sub-agents needed.
Then check scope drift, in both directions:
- Diff changes not traceable to any in-scope FR (list them; small hardening/refactors that came from code review are normal — note them, don't inflate them into findings)
- Anything that implements an item on the Out of Scope — Do NOT Build list — this is always a finding (the PRD treats gold-plating as a defect)
- Every guard AC from the contract, as a static check: does the diff introduce what this
guard forbids? Read the guard's Then (the element text, route, column, job, or unchanged
behavior it says must be absent) and search the diff for it — a new route or link matching
the text, a migration adding the column, a job enqueue, a change to the behavior it
preserves. Record each guard as HELD (nothing in the diff introduces it) or VIOLATED
(cite the file/line). A violated guard is always a finding under Scope Drift, regardless
of whether the same item is also caught by the Out-of-Scope list above. Guards do not
appear in the AC trace table as IMPLEMENTED/PARTIAL/MISSING — held/violated is their whole
status here; whether the absence was observed is
/verify-acceptance's job.
Exclude pipeline/working artifacts from drift analysis entirely: anything under
.claude/ (plans, tickets, reviews, bug-reports, prds), docs/qa-plans/,
docs/bug-reports/, tmp/, and screenshots. They are not product changes.
Phase 4: Write the Report
Save to .claude/requirement-traces/trace-{feature-slug}-{YYYYMMDD}.md (create the directory
if it doesn't exist):
# Requirements Trace: [Feature Name]
**PRD**: [path]
**Contract**: [`.claude/acceptance-criteria/<slug>.md` — Review status: … | "none"]
**Branch**: [branch] (base: main)
**Analyzed**: [date] — [N] commits, [N] files changed
---
## Executive Summary
[2-3 sentences: how complete the implementation is, where the gaps concentrate.]
**Verdict**: FULLY TRACED | GAPS FOUND | SIGNIFICANT GAPS
[FULLY TRACED = every FR and DoD item IMPLEMENTED. SIGNIFICANT GAPS = any Must-priority FR
is MISSING. Otherwise GAPS FOUND. If the PRD has no DoD section, the verdict rests on the
FRs alone.]
**FRs implemented**: X/Y (Must: X/Y, Should: X/Y) • **Acceptance Criteria (static)**: X/Y • **Guards held**: X/Y • **Definition of Done**: X/Y
---
## Functional Requirements Trace
### [Category from PRD]
| FR | Priority | Status | Evidence (files/specs) | Notes |
|----|----------|--------|------------------------|-------|
| FR-1 | Must | IMPLEMENTED | `app/services/x.rb` (`#call`), `spec/services/x_spec.rb` | |
| FR-2 | Must | PARTIAL | `app/controllers/y_controller.rb` | Sort param accepted but ignored — acceptance criterion "user can sort by date" unmet |
| FR-3 | Should | MISSING | — | No evidence in diff |
---
## Acceptance Criteria Trace (static)
| AC | Type | Source | Priority | Verified by | Status | Evidence | Notes |
|----|------|--------|----------|-------------|--------|----------|-------|
| AC-1 | feature | FR-1 | Must | browser | IMPLEMENTED | `app/...`, `spec/...` | |
[Static only: "code + spec that would satisfy this exists". Whether it was *observed* to hold
is `/verify-acceptance`'s job, later in the pipeline. Guard rows are reported under Scope
Drift, not here. `N/A — no contract file; run /acceptance-criteria` if there is no contract.]
## Definition of Done Trace
| Item | Status | Evidence |
|------|--------|----------|
| [checkbox text] | IMPLEMENTED / PARTIAL / MISSING | [files] |
---
## Scope Drift
- **Out-of-scope violations**: [changes implementing "Do NOT Build" items, or "None"]
- **Guard ACs**: [one line per guard row — `AC-n (OOS-m): HELD` or `AC-n (OOS-m): VIOLATED — file:line introduces …`; or "N/A — no contract file"]
- **Untraceable changes**: [diff work not mapping to any FR — one line each, or "None"]
---
## Gaps & Recommended Actions
[One entry per PARTIAL/MISSING item and per VIOLATED guard, written like a ticket an
implementer can execute without re-derivation: the FR/AC, what exactly is absent (or, for a
guard, what must be removed), which files to create/modify, and which precedent in the
diff/codebase to pattern-match. Must-priority gaps first.]
1. **FR-2 (Must, PARTIAL)**: Wire the `sort` param in `YController#index` into the query
(see `XController#index` for the precedent); add a controller spec for both sort orders.
---
## Ambiguities & Recommended Defaults
[This report is often consumed by an autonomous pipeline where no one can answer questions.
For each judgment call you had to make (e.g., an FR whose acceptance criterion is only
verifiable in a browser), state the issue AND the default you applied.]End your response with the verdict line, the X/Y counts, and the report path.
Principles
- Report-only. Never edit application code, specs, the PRD, or the contract — even for a one-line gap. The caller owns remediation.
- Evidence over inference. Every IMPLEMENTED status cites files you actually read. If you didn't read it, it isn't evidence.
- Must gaps are the headline. A MISSING Should is a note; a MISSING Must is the verdict.
- The PRD is the whole scope; the contract's guards are its fence. Don't invent
requirements the PRD doesn't state, and don't grade code quality —
/full-reviewowns that. - Honest PARTIALs. The value of this gate is in the precise "what's absent" — vague PARTIALs are unactionable and worse than either clean status.
Begin by resolving the PRD and the contract.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

