agile-epic-validate

name	agile:epic:validate
description	Final quality gate that comprehensively validates an epic implementation against its design, plan, specs, and tasks before marking it COMPLETED. Dispatches parallel validation agents across 5 domains (artifact consistency, task completion, build verification, constitution compliance, acceptance criteria) and produces a structured PASS/FAIL verdict. Use this skill whenever the user wants to validate an epic, verify epic completion, check if an epic is done, run a final quality gate, confirm all features are implemented, or mentions "validate epic", "verify epic", "epic done?", "close epic", "complete epic", "mark epic completed", or any request to confirm epic implementation correctness. Also use proactively after epic implementation finishes to ensure nothing was missed.
user-invocable	true
disable-model-invocation	false
allowed-tools	["Read","Edit","Write","Glob","Grep","Bash","Agent","Skill","TaskCreate","TaskList","TaskGet","TaskUpdate","AskUserQuestion"]

Epic Validate

Final quality gate for an epic. Validates that every feature was implemented correctly according to design, plan, spec, and task definitions — then marks the epic COMPLETED if all gates pass.

Invocation

• /agile:epic:validate — Auto-detect epic (looks for IMPLEMENTING epics)
• /agile:epic:validate 153 — Target specific epic number
• /agile:epic:validate agile/epics/153-convention-plugin — Target specific path

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Context

• Current branch: !git branch --show-current
• Recent epics: !ls agile/epics/ 2>/dev/null | sort | tail -5

Hard Gate

Do NOT mark any epic as COMPLETED unless ALL validation gates pass. Partial completion is not supported. This prevents the state drift identified in Report 009 and Epic 078. If ANY gate fails, the epic remains in its current status and the skill produces a remediation report instead.

Identification Format

Level	Format	Example
Epic	NNN	153
Feature	NNN-XX	153-01
User Story	NNN-XX-U{n}	153-01-U1
Task	NNN-XX-T{nn}	153-01-T03

Phases

• Phase 1: Resolve context and verify prerequisites
• Phase 2: Dispatch parallel validation agents (5 domains)
• Phase 3: Collect results and compute verdict
• Phase 4: Report and act (mark COMPLETED or produce remediation)
• Phase 5: Post-completion actions (learnings, DevOps sync, next steps)

---

Phase 1: Resolve Context & Verify Prerequisites

1.1 Resolve Epic Directory

Resolve $ARGUMENTS to EPIC_DIR using this priority chain:

1. If argument is a 3-digit number (e.g., 153): search agile/epics/ for directory starting with that number
2. If argument is a path: use directly
3. If no argument: scan agile/epics/ for directories where epic.md has status IMPLEMENTING, IMPLEMENTED, or VALIDATED
4. If exactly one candidate → use it. Multiple → AskUserQuestion to choose. None → error and stop.

1.2 Verify Prerequisites (hard gates)

All of these must exist or the skill exits with an error:

Artifact	Location	Error if Missing
epic.md	EPIC_DIR/epic.md	"No epic specification found. Run /agile:epic:plan"
design.md	EPIC_DIR/design.md	"No design found. Run /agile:epic:brainstorm"
plan.md	EPIC_DIR/plan.md	"No plan found. Run /agile:epic:plan"
Features	EPIC_DIR/NNN-XX-*/	"No feature directories found"
Feature specs	Each feature has spec.md	Warning per missing spec (not hard gate)
Feature tasks	Each feature has tasks.md	Warning per missing tasks (not hard gate)

1.3 Load Epic Context

Read and extract from epic.md:

• Epic name and status (metadata header)
• Feature breakdown table (feature IDs, names, stages)
• Success criteria / acceptance criteria section
• Dependencies section
• Key decisions section

Read design.md:

• Problem statement (what the epic aimed to solve)
• Success criteria (measurable outcomes from design phase)

Read plan.md:

• Scope quantification (claimed file counts, error counts)
• Milestones and phase gates

1.4 Build Feature Inventory

For each feature directory NNN-XX-*:

• Read spec.md status line
• Read tasks.md and count markers by type
• Record: feature ID, name, spec status, task counts

Output: FEATURE_INVENTORY — array of feature records used by all validation agents.

---

Phase 2: Dispatch Parallel Validation Agents

Launch 5 validation agents in parallel using the Agent tool. Each agent receives the EPIC_DIR path, FEATURE_INVENTORY, and its specific validation domain. Each agent returns a structured result.

Agent 1: Artifact Consistency Validator

Purpose: Verify the three sources of truth agree on feature status.

Checks:

1. Three-source agreement — For each feature, compare:

   • tasks.md markers → derive status using bottom-up rules (see Status Derivation below)
   • spec.md **Status**: line (IMPLEMENTED, COMPLETED, and VALIDATED are equivalent terminal states)
   • epic.md feature breakdown table stage column (IMPLEMENTED, COMPLETED, and VALIDATED are equivalent terminal states)
   • If any two disagree on terminal vs non-terminal → FAIL with specific mismatch details

2. Task ID integrity — Every task in tasks.md follows NNN-XX-T{nn} format. No duplicates.

3. Spec-to-task traceability — Each FR-* requirement in spec.md has at least one task referencing it in tasks.md.

4. Cross-feature dependency consistency — Tasks with :NNN-YY-T{nn} dependency notation reference tasks that actually exist in the other feature's tasks.md.

Output: { gate: "artifact_consistency", passed: bool, issues: [...] }

Agent 2: Task Completion Validator

Purpose: Verify all tasks reached terminal state and counts are correct.

Checks:

1. All tasks terminal — Every task in every feature's tasks.md must be [X] (completed) or [S] (skipped). Tasks marked [ ], [W], [-], or [B] indicate incomplete work.

2. Completion percentage — For each feature: completed / (total - skipped) * 100 must be 100%.

3. Cross-cutting tasks — If tasks.md has a "Cross-Cutting Concerns" or "Polish" phase, verify all CT-* tasks are [X] or [S].

4. Skipped task justification — Any [S] task should have a reason after the marker (: notation). Warn if missing but don't fail.

5. state.json alignment (if exists) — completedFeatures in state.json matches features with 100% tasks.

Output: { gate: "task_completion", passed: bool, issues: [...], summary: { total, completed, skipped, remaining } }

Agent 3: Build Verification Agent

Purpose: Verify the codebase actually compiles and tests pass for affected modules.

Checks:

1. Detect build system — Check for gradlew (Gradle) or pom.xml (Maven). Use the appropriate command.

2. Identify affected modules — Parse epic.md and design.md for module references (e.g., services/core, workers/batch).

3. Compile check — For each affected module:

   # Gradle
   ./gradlew :module:compileJava -x test 2>&1 | tee .context/terminal/validate_compile_$(date +%s).log
   # Maven
   mvn clean compile -pl module -DskipTests 2>&1 | tee .context/terminal/validate_compile_$(date +%s).log
   

   Check for BUILD SUCCESSFUL / BUILD SUCCESS.

4. Test check — Run tests for affected modules:

   # Gradle
   ./gradlew :module:test 2>&1 | tee .context/terminal/validate_test_$(date +%s).log
   

   Count test passes/failures.

5. Post-build error comparison — If design.md claimed N errors, verify current error count is 0 (or reduced to the expected level).

Output: { gate: "build_verification", passed: bool, issues: [...], buildResults: { module, compileStatus, testStatus, errorCount } }

Note: If build tools are unavailable or the epic is documentation-only, this gate becomes advisory (pass with warning).

Agent 4: Constitution Compliance Validator

Purpose: Verify the implementation adheres to applicable constitutions.

Checks:

1. Identify applicable constitutions — Based on affected modules:

   • Always: .agile/rules/constitution.md (master)
   • If services/*: .agile/rules/services/constitution.md
   • If workers/*: .agile/rules/workers/constitution.md
   • If common/*: .agile/rules/common/constitution.md
   • If frontend/*: .agile/rules/frontend/constitution.md

2. Naming convention check (MASTER:V) — Scan for prohibited abbreviations: cust, config (as variable), dept, info, repo (as variable), svc, util, Req, Res, TO

3. Entity package convention (COMMON:III) — If entities were created/modified, verify they follow the correct package structure per CLAUDE.md entity table.

4. Test coverage (MASTER:III) — Verify test files exist for new source files. Check that test directories mirror source directories.

5. Import hierarchy — If files span multiple tiers, verify import direction follows the three-tier hierarchy (Tier 1 → Tier 2 → Tier 3, never reversed).

Output: { gate: "constitution_compliance", passed: bool, issues: [...], constitutionsChecked: [...] }

Note: Constitution compliance is advisory — issues generate warnings, not hard failures. The user decides whether to fix or waive.

Agent 5: Acceptance Criteria Validator

Purpose: Verify the epic's success criteria and acceptance criteria are met.

Checks:

1. Epic success criteria — Read epic.md and design.md success criteria sections. For each criterion:

   • If measurable (e.g., "0 build errors", "compile time < 30s"): attempt automated verification
   • If subjective (e.g., "improved developer experience"): mark as MANUAL_REVIEW
   • If verifiable by grep/build (e.g., "no Lombok imports"): run the check

2. Milestone verification — If plan.md defines milestones or phase gates, verify each is met.

3. Dependency output verification — If epic.md declares dependency epics, verify their outputs are actually used in the current epic's implementation (grep for imports, references).

4. Feature acceptance criteria — For each feature's spec.md, check the acceptance criteria section. Where automatable, verify. Otherwise, mark for manual review.

Output: { gate: "acceptance_criteria", passed: bool, issues: [...], criteria: [{ criterion, status: "VERIFIED"|"MANUAL_REVIEW"|"FAILED", evidence }] }

---

Status Derivation Rules

Used by validation agents to derive status from task markers (bottom-up):

Task Level (read directly from tasks.md)

Marker	State
[ ]	Pending
[W]	In Progress
[X]	Completed
[-]	Partial
[B]	Blocked
[S]	Skipped

User Story Level (derived)

Status	Condition
COMPLETED	ALL tasks are [X] or [S]
IMPLEMENTING	Any [W] or mix of [X] and [ ]
BLOCKED	Any [B] present
PENDING	ALL tasks are [ ]

Feature Level (derived)

Status	Condition
IMPLEMENTED	ALL user stories COMPLETED
COMPLETED	Synonym for IMPLEMENTED (post-validation)
VALIDATED	Synonym for IMPLEMENTED (e2e confirmed)
IMPLEMENTING	Any user story IMPLEMENTING
BLOCKED	Any story BLOCKED, none IMPLEMENTING
PENDING	ALL stories PENDING
SKIPPED	Feature explicitly skipped

Epic Level (derived)

Status	Condition
COMPLETED	ALL features terminal (IMPLEMENTED/COMPLETED/VALIDATED or SKIPPED)
VALIDATED	Synonym for COMPLETED (e2e build confirmed)
IMPLEMENTING	Any feature IMPLEMENTING
BLOCKED	All remaining features BLOCKED
PARTIAL	Some terminal, some BLOCKED/SKIPPED
PENDING	ALL features PENDING

---

Phase 3: Collect Results & Compute Verdict

Wait for all 5 agents to complete. Collect their structured outputs.

Verdict Rules

Verdict	Condition
PASS	All 5 gates passed (constitution gate is advisory — warnings OK)
FAIL	Any non-advisory gate failed
PASS WITH WARNINGS	All hard gates passed, but advisory gates have warnings

Gate Classification

Gate	Type	Failure blocks completion?
Artifact Consistency	Hard	Yes
Task Completion	Hard	Yes
Build Verification	Hard (soft for doc-only epics)	Yes
Constitution Compliance	Advisory	No (warnings only)
Acceptance Criteria	Hard	Yes (except MANUAL_REVIEW items)

---

Phase 4: Report & Act

If PASS or PASS WITH WARNINGS

1. Update epic status — Edit epic.md: if status is IMPLEMENTING, change → **Status**: COMPLETED. If already VALIDATED, leave as-is.

2. Update feature statuses — For each feature:

   • Edit spec.md: if status is non-terminal, change → **Status**: IMPLEMENTED. If already COMPLETED or VALIDATED, leave as-is.
   • Edit epic.md feature table: if stage is non-terminal, change → COMPLETED. If already VALIDATED, leave as-is.

3. Update state.json (if exists):

   • Set epicStatus: "COMPLETED" (or leave as "VALIDATED" if already set)
   • Set currentPhase: "validated"
   • Add checkpoint entry

4. Generate validation report — Write EPIC_DIR/validation-report.md:

# Validation Report: Epic NNN — [Epic Name]

**Date**: [timestamp]
**Verdict**: PASS / PASS WITH WARNINGS
**Validated by**: agile:epic:validate skill

## Gate Results

| Gate | Status | Details |
|------|--------|---------|
| Artifact Consistency | PASS | 3-source agreement verified for N features |
| Task Completion | PASS | X/Y tasks completed, Z skipped |
| Build Verification | PASS | All modules compile, N tests pass |
| Constitution Compliance | PASS (N warnings) | [warnings listed] |
| Acceptance Criteria | PASS | N/M criteria verified, K manual review |

## Feature Summary

| Feature | Tasks | Status | Notes |
|---------|-------|--------|-------|
| NNN-01 | 12/12 | IMPLEMENTED | |
| NNN-02 | 8/8 | IMPLEMENTED | 1 skipped (justified) |

## Acceptance Criteria

| Criterion | Status | Evidence |
|-----------|--------|----------|
| Zero build errors | VERIFIED | BUILD SUCCESSFUL |
| All tests pass | VERIFIED | 142 tests, 0 failures |

## Warnings (if any)

[List advisory warnings here]

5. Present to user — Display a summary dashboard showing the verdict and key metrics.

If FAIL

1. Do NOT update any status — Leave everything as-is.

2. Generate remediation report — Write EPIC_DIR/validation-report.md with FAIL verdict:

# Validation Report: Epic NNN — [Epic Name]

**Date**: [timestamp]
**Verdict**: FAIL
**Blocking Issues**: N

## Failed Gates

### [Gate Name]: FAILED

**Issues**:
1. [Specific issue with file path and line reference]
2. [Another issue]

**Remediation**:
- [Specific action to fix each issue]

## Recommended Next Steps

1. Fix the N blocking issues listed above
2. Re-run: `/agile:epic:validate NNN`

3. Present failure summary to user with specific remediation actions.

4. Offer handoffs:

   • "Fix issues and re-validate" → user fixes manually, re-runs this skill
   • "Run /agile:epic:implement to address gaps" → if features need more work
   • "Run /agile:epic:progress to see current state" → if user wants dashboard first

---

Phase 5: Post-Completion Actions (only on PASS)

5.1 Capture Learnings (optional, non-blocking)

Spawn agile-observer agent (if available) to capture execution learnings. If unavailable, skip with a warning — this does not block completion.

5.2 Sync to Azure DevOps (optional, non-blocking)

If the DevOps MCP server is available:

• Update the epic work item status to COMPLETED
• Update feature work items
• Add validation report as a comment

If unavailable, log a warning and proceed. Suggest user run /devops:workitem push NNN manually.

5.3 Suggest Next Steps

Present options to the user:

• "Commit validation results" → git add the validation report and updated artifacts
• "Create PR for epic completion" → if on a feature branch
• "Run /agile:epic:priority to see what's next" → prioritize remaining backlog
• "Archive and move on" → no further action needed

---

Error Handling

Scenario	Behavior
Agent times out	Report partial results, mark timed-out gate as INCONCLUSIVE
Build tools unavailable	Mark build gate as ADVISORY, proceed with other gates
state.json missing	Skip state.json checks, proceed with file-based validation
Feature has no tasks.md	Warn but don't fail — count as 0 tasks (advisory)
Constitution file missing	Skip that constitution, warn in report
Epic has 0 features	FAIL — "Epic has no features. Nothing to validate."
All features skipped	PASS — epic is vacuously complete (with prominent warning)

---

Quick Reference: Validation Checklist

This is the condensed checklist the skill evaluates:

• All features have terminal task status (every task is [X] or [S])
• tasks.md, spec.md, and epic.md agree on feature status
• Task IDs are valid and non-duplicate
• Spec requirements trace to tasks
• Cross-feature dependencies reference real tasks
• Affected modules compile successfully
• Tests pass for affected modules
• Epic acceptance criteria are met
• Naming conventions follow constitution
• No prohibited abbreviations in new code
• Import hierarchy respects three-tier structure
• Dependency epic outputs are actually used