Review Frs

Review FRS

Audit-only skill. Reads an existing FRS (file or paste) and emits structured findings against the canonical validation contract in .claude/shared/frs-validation-rules.md. No writes, no GitLab calls, no FRS generation. For generating a new FRS, use skill:generate-frs.

Announce at start: "I'm using the review-frs skill to audit your FRS against the canonical validation contract."

When to Use

Use when the user wants an existing FRS evaluated for quality, completeness, contract compliance, or readiness for stakeholder approval. Accepts an FRS as a file path, a pasted body, or a GitLab issue URL (the user pastes the body — this skill does not call GitLab).

Do NOT use for: generating a new FRS (skill:generate-frs), tech-spec review, code review, design review.

Process

Complete in order. Each phase is described in detail below.

0. Preflight — verify the four shared references exist and snapshot the contract version stamps.
1. Read & structural pass — confirm the input is an FRS; iterate the canonical section list and flag missing / out-of-order / spurious sections.
2. Apply the contract — Skill Constraint, Self-Review checklist (currently 14 items; legend in frs-validation-rules.md is authoritative), Severity Guide, NFR Rubric, Bundling Detection, AC↔FR traceability, glossary resolution, cross-cutting non-duplication, OQ tag taxonomy.
3. Compose findings — produce a structured audit report in the format defined below.
4. User disposition — present the finding count and let the user choose next steps.

Phase 0 — Preflight

Read these four references and snapshot their versions:

Read('.claude/shared/frs-template.md')          # plugin-owned
Read('.claude/shared/frs-validation-rules.md')  # plugin-owned
Read(<glossary_path>)                           # project-owned; default docs/glossary.md
Read(<cross_cutting_path>)                      # project-owned; default docs/cross-cutting-concerns.md

The plugin-owned references are at .claude/shared/. The project-owned references are resolved from CLAUDE.md's glossary_path and cross_cutting_path keys; if either is absent, fall back to the defaults above. If a resolved file is missing, halt with the path-specific directed message:

• For a missing glossary file: "Project reference <resolved glossary path> is not present. Run agent:glossary-curator with operation Initialize to seed it from the plugin template, or update CLAUDE.md's glossary_path key to point at an existing file. Then re-run the audit."
• For a missing cross-cutting-concerns file: "Project reference <resolved cross-cutting path> is not present. Run agent:cross-cutting-curator with operation Initialize to seed it from the plugin template, or update CLAUDE.md's cross_cutting_path key to point at an existing file. Then re-run the audit."

Capture the version stamps (frs_template_version, validation_rules_schema, glossary_version, baseline_version — the last name is preserved for backward compatibility with prior audit logs). They appear in the audit report's reproducibility footer so a later reader can reconstruct exactly which contract was applied.

The audit cannot proceed against a partial contract.

Phase 1 — Read & Structural Pass

1a. Read the input. If the input is a file path, Read it. If a paste, work from the paste directly. If neither, AskUserQuestion:

AskUserQuestion(questions=[{
  question: "How is the FRS provided?",
  header: "Input",
  multiSelect: false,
  options: [
    { label: "File path",      description: "I'll provide a path under /mnt/user-data/uploads/ in my next message." },
    { label: "Paste",          description: "I'll paste the FRS body in my next message." },
    { label: "Cancel",         description: "Stop the audit; no findings produced." }
  ]
}])

1b. Confirm it's an FRS. Iterate the Canonical Section List from frs-template.md. The input is an FRS if its markdown headers, in order, structurally match the list (capitalization tolerated, numbering tolerated). If the structural match fails outright, the input is not an FRS — surface this as the only finding and stop.

1c. Structural findings. For each section in the Canonical Section List, classify:

• Present and in order → no finding.
• Missing → Blocker (per Severity Guide).
• Out of order → Minor.
• Empty (and "None" not stated, and not in the None-valid set per frs-validation-rules.md § FRS Structure) → Major or Blocker per the rules.

For each section heading present in the FRS that is NOT in the Canonical Section List → Major (spurious section).

Phase 2 — Apply the Contract

Run each rule from frs-validation-rules.md in order:

2a. Skill Constraint. Count business rules (Section 20), edge cases (Section 21), exception flows (Section 12). Each minimum violation = Blocker.

2b. Self-Review checklist (currently 14 items; iterate the legend in frs-validation-rules.md rather than hardcoding the count). For each item in the checklist, evaluate the FRS:

For each item, produce the corresponding character (P / F / R is generation-time only — for review, just P for pass and a finding for fail) and, if fail, a finding entry per Section 3 below.

2c. Severity Guide. Each finding must be classified Blocker / Major / Minor per the table in frs-validation-rules.md.

2d. NFR Rubric. Every entry in Section 18 must (a) be in business language, (b) be operation-specific, (c) not restate cross-cutting content. Apply the rubric examples from the rules file.

2e. AC ↔ FR Traceability. Cross-check the AC table (Section 17) against the FR table (Section 16):

• Every Must-priority FR in Section 16 must be cited by ≥1 AC's Traces to column. List untraced FRs as Blocker findings.
• Every AC in Section 17 must have a non-empty Traces to column. List untraced ACs as Blocker findings.
• Every FR-ID cited in Traces to must exist in Section 16. List dangling references as Major.
• ACs that restate an FR verbatim ("AC-NN: The system shall …") are Minor.

2f. Glossary Resolution. For every term in Section 4, look up the entry in docs/glossary.md. Missing entries → Major (term unresolved). For every domain-looking term used in the body but not in Section 4 → Minor (probable missing reference). Use judgement on what counts as a "domain term" — proper nouns of business artefacts are the strong signal.

2g. Bundling Detection. Apply the signals from frs-validation-rules.md § Bundling Detection. Multiple actors, multiple triggers, multiple disjoint state transitions → Blocker.

2h. OQ Tag Taxonomy. Section 22's OQs must each carry one of [blocking] / [post-approval] / [deferred]. Untagged → Major. [deferred] without an enhancement reference → Minor.

2i. [inferred from code] Tag Compliance. If the FRS body contains any [inferred from code] tag in BR / EC / Exception / Actors / Form Fields validation, verify Section 22 carries an OQ for that item (per frs-code-extraction-rules.md § Propagation). Inferred items without a corresponding OQ → Major.

Phase 3 — Compose the Audit Report

The report is the deliverable. Format:

# FRS Audit Report

**FRS:** <FRS-ID and title from the input>
**Audited against:** validation-rules schema vN.M, template vX.Y, glossary vX.Y, cross-cutting concerns vX.Y
**Audit date:** <ISO 8601>
**Verdict:** PASS | PASS_WITH_MAJORS | FAIL

---

## Summary

- Blockers: N
- Majors: N
- Minors: N

## Blockers

### B-01 — <Severity Guide row name>

**Section:** <which FRS section, e.g., "Section 17 (Acceptance Criteria)">
**Quote:** "<verbatim quote from the FRS that triggered this finding>"
**Issue:** <one-paragraph explanation referencing the rule from `frs-validation-rules.md`>
**Rewrite:**

> <concrete proposed rewrite — same scope, satisfies the rule>

**Rule reference:** `frs-validation-rules.md` § <section name>

(repeat per Blocker)

## Majors

(same shape — M-01, M-02, ...)

## Minors

(same shape — m-01, m-02, ... lowercase to distinguish from Majors visually)

## Self-Review Checklist Result

(<N>-character status string aligned to the legend in `frs-validation-rules.md`)
P P F P P P P P F P P P F F
1 2 3 4 5 6 7 8 9 10 11 12 13 14
   ↑ no-tech                 ↑ baseline-not-duplicated
                                ↑ ac-fr-traceable

(items showing F have a corresponding finding above; items showing P need no entry)

## Audit Reproducibility

- Validation rules version: <vN.M>
- Template version: <vX.Y>
- Glossary version: <vX.Y>
- Cross-cutting concerns version: <vX.Y>
- Audit performed by: skill:review-frs

Verdict thresholds (per frs-validation-rules.md § Severity Guide):

• PASS — zero Blockers AND zero Majors. Minors only (or clean).
• PASS_WITH_MAJORS — zero Blockers, ≥1 Major.
• FAIL — ≥1 Blocker.

Phase 4 — User Disposition

After presenting the report:

AskUserQuestion(questions=[{
  question: "Audit complete: <Verdict> ({B} Blockers, {M} Majors, {m} Minors). What next?",
  header: "Disposition",
  multiSelect: false,
  options: [
    { label: "Generate revisions",   description: "I'll list specific findings I want addressed; you'll respond with concrete rewrites for each." },
    { label: "Drill into a finding", description: "Pick one finding for deeper analysis (rule context, comparable examples)." },
    { label: "Done",                 description: "Audit accepted; close the session." }
  ]
}])

If the user picks "Generate revisions", produce rewrites for each named finding. Note that this skill does NOT modify the FRS — the rewrites are advisory text the user applies elsewhere (or via skill:generate-frs's revision sub-loop if the FRS is a current-run output).

References (loaded at Phase 0)

Common Mistakes

❌ Auditing without reading frs-validation-rules.md — your findings will drift from the contract. ❌ Producing findings without verbatim quotes — they're not auditable. ❌ Inventing rules ("the Purpose section should be three sentences max") — only rules in the validation file are findings. ❌ Recommending tech-stack changes — out of scope; the FRS is business language only. ❌ Treating absent sections as Minors when the rules say Blocker. ❌ Skipping the AC↔FR cross-check because "ACs look fine in isolation" — the traceability rule is bidirectional. ❌ Hardcoding the section count in the audit logic — iterate the canonical list.

Integration

Required before: the two plugin-owned references in .claude/shared/ (frs-template.md, frs-validation-rules.md) and the two project-owned references resolved from CLAUDE.md (glossary_path, cross_cutting_path — defaults docs/glossary.md and docs/cross-cutting-concerns.md). No GitLab connectivity required (this skill is read-only and never calls external services).

vs. skill:generate-frs: that skill writes new FRS. This one audits existing ones. Both share frs-validation-rules.md as canonical contract — never duplicate it.

Output: the audit report in chat. No file writes. No GitLab updates. The user applies findings manually or pipes them into generate-frs's revision sub-loop.