Epic Verification & Auditing
Relevant source files
The following files were used as context for generating this wiki page:
Epic Verification & Auditing encompasses the pre-implementation review and post-implementation assessment of complex features (Epics) within the Roughly framework. The system ensures that high-level specifications are technically sound, risk-mitigated, and ultimately satisfied by the delivered code. This is achieved through two primary workflows: review-epic for proactive quality assurance and audit-epic for retrospective verification.
These processes rely on specialized subagents, notably the epic-reviewer (powered by the Opus model), to perform cross-story reasoning and identify structural impossibilities, such as conflicting acceptance criteria (AC) or overengineering, before implementation begins. Post-implementation, the auditing system maps implementation history to specific story IDs to verify that all ACs are met.
Sources: README.md:90-110, agents/epic-reviewer.md:1-15, CLAUDE.md:68-68
Pre-Implementation: Epic Review
The Epic Review process is a proactive stage designed to catch technical issues and risks while they are inexpensive to fix. It is invoked via the /roughly:review-epic command and targets Epic files, typically located in docs/epics/.
Review Dimensions and Logic
The epic-reviewer agent analyzes the epic across seven specific dimensions to ensure implementation success:
- Technical Accuracy: Feasibility of proposed approaches within the existing codebase.
- Best Practices: Adherence to established project patterns.
- Risks: Identification of missing edge cases, integration risks, and scaling concerns.
- Overengineering: Elimination of unnecessary complexity.
- AC Quality: Ensuring acceptance criteria are specific, testable, and complete.
- Dependencies: Correct ordering and identification of cross-story dependencies.
- AC Mutual Satisfiability: A critical check for structural impossibilities where two ACs might jointly create a requirement that cannot be met (e.g., conflicting constraints on the same file path or step).
Sources: skills/review-epic/SKILL.md:1-35, agents/epic-reviewer.md:20-35
Review Workflow
The following diagram illustrates the flow from epic submission to the final review report:
This flowchart describes the sequential steps taken by the orchestrator to validate an epic and dispatch the Opus-based reviewer agent.
Sources: skills/review-epic/SKILL.md:19-45, agents/epic-reviewer.md:17-25
Post-Implementation: Epic Audit
The Audit Epic process (/roughly:audit-epic) verifies that a completed epic's implementation matches its original specification. Unlike implementation pipelines, this skill does not modify source code; it only generates an audit report.
Audit Steps
| Step | Action | Description |
|---|---|---|
| 1 | Parse Epic | Extracts story IDs, ACs, and technical requirements. |
| 2 | Map Stories | Uses git log to identify files associated with specific story IDs. |
| 3 | Per-Story Review | Dispatches subagents to check if each AC is MET, PARTIALLY MET, or NOT MET. |
| 4 | Cross-Cutting Review | Analyzes consistency, integration, and gaps across the entire epic implementation. |
| 5 | Report Synthesis | Generates a final *-audit.md report with prioritized recommendations. |
Sources: skills/audit-epic/SKILL.md:1-125
Implementation-to-Story Mapping
To verify implementation, the auditor must map code changes back to the specification. It utilizes Git history to find commits associated with Story IDs.
The sequence diagram shows how the auditor maps implementation artifacts to story specifications using Git metadata before dispatching subagents for verification.
Sources: skills/audit-epic/SKILL.md:46-95
Plan Verification: AC Satisfiability
A critical component of auditing and reviewing is ensuring that individual tasks within a plan are verifiable and satisfy acceptance criteria without contradiction. The review-plan skill (dispatched by build/fix pipelines) performs deep verification of these criteria.
Verification Patterns
- Enumeration Check: Every edit site (line numbers, ranges) must be explicitly listed unless "structural uniformity" is claimed.
- Signal Source Naming: Any runtime detection (e.g., branch name, file content) must name the observable signal source.
- Self-Defeating Patterns: Verify commands must not search for literals that are part of the new detection prose itself.
- Co-location Hazards: Avoid
grep -Fcif multiple matching sites could land on the same physical line.
Sources: skills/review-plan/SKILL.md:36-80
AC Joint Satisfiability Matrix
When reviewing ACs, the system checks for overlaps across three dimensions. If any dimension is shared, the satisfiability check is triggered.
| Shared Dimension | Check Status | Logic |
|---|---|---|
| Same File | Active | Potential for conflicting file states or line counts. |
| Same Step | Active | Potential for conflicting logic at the same execution gate. |
| Same Prose Region | Active | Potential for overlapping textual modifications. |
| Different File AND Step | Skip | ACs are considered orthogonal. |
Sources: skills/review-plan/SKILL.md:120-135, agents/epic-reviewer.md:34-34
Audit & Review Outputs
Both processes generate structured reports saved alongside the original epic file.
Audit Report Structure
# Epic Audit: [Epic Title]
**Acceptance criteria:** [Total] — [Met] MET, [Partial] PARTIAL, [Not Met] NOT MET
## Summary
[High-level assessment]
## Per-Story Results
| AC | Status | Evidence |
|----|--------|----------|
| [AC Text] | MET | [file:line] |
## Recommendations
- [Prioritized issues to address]
Sources: skills/audit-epic/SKILL.md:110-125
Epic Review Verdicts
The epic-reviewer provides a summary verdict to the orchestrator:
- Ready: No blockers; implementation can proceed.
- Needs Revision: Minor issues found in ACs or technical approach.
- Major Concerns: Blockers identified (e.g., AC unsatisfiability or high integration risk).
Sources: agents/epic-reviewer.md:40-60, skills/review-epic/SKILL.md:47-55
Summary
Epic Verification & Auditing provides the "loud" and gated oversight necessary for managing complex changes in Roughly. By using the epic-reviewer for pre-implementation Opus-level analysis and structured Sonnet subagents for post-implementation auditing, the system ensures that epics are not only theoretically sound but also correctly and completely implemented across all specified acceptance criteria.