Validation Loop Skill

Autonomous verification loop that runs 8 specialized agents and fixes issues until all approve.

Prerequisites

Before invoking this skill, ensure:

Implementation is complete
Tests pass
Changes are ready for review

Workflow

1. Gather Context

CRITICAL — Context budget: Do NOT read file contents, full diffs, specs, or architecture docs into this orchestrating context. Collect only file paths and metadata. Agents have Read/Grep/Glob tools and will read files in their own context windows.

Collect for the agents:

Changed file paths: git diff --name-only HEAD~1 → list of paths (keep, small)
Diff stat: git diff --stat HEAD~1 → brief change summary (lines added/removed per file)
Test file paths: identify associated test files by convention (do NOT read them)
Task definition (goal, action items, acceptance criteria) → keep, brief
Specs path: path to specs/product_specs.md or specs/product_specs/ (do NOT read contents)
Architecture path: path to specs/architecture.md or specs/architecture/ (do NOT read contents)
Design system path: path to specs/design_system.md or specs/design_system/ (do NOT read contents)

2. Launch Verification Agents

Use Task tool to launch all 8 agents in parallel:

Agent (`subagent_type`)	Context to Provide
`groundwork:code-quality-reviewer:code-quality-reviewer`	`changed_file_paths`, `diff_stat`, `task_definition`, `test_file_paths`
`groundwork:security-reviewer:security-reviewer`	`changed_file_paths`, `diff_stat`, `task_definition`
`groundwork:spec-alignment-checker:spec-alignment-checker`	`changed_file_paths`, `diff_stat`, `task_definition`, `specs_path`
`groundwork:architecture-alignment-checker:architecture-alignment-checker`	`changed_file_paths`, `diff_stat`, `task_definition`, `architecture_path`
`groundwork:code-simplifier:code-simplifier`	`changed_file_paths`, `diff_stat`, `task_definition`
`groundwork:housekeeper:housekeeper`	`changed_file_paths`, `diff_stat`, `task_definition`, `task_status`, `specs_path`, `architecture_path`, `design_system_path`
`groundwork:performance-reviewer:performance-reviewer`	`changed_file_paths`, `diff_stat`, `task_definition`
`groundwork:design-consistency-checker:design-consistency-checker`	`changed_file_paths`, `diff_stat`, `design_system_path`

In each agent prompt, include: "Use the Read tool to examine these files. Do NOT expect file contents in this prompt — read them yourself."

Each returns JSON:

{
  "summary": "One-sentence assessment",
  "score": 0-100,
  "findings": [{"severity": "critical|major|minor", "category": "...", "file": "...", "line": N, "finding": "...", "recommendation": "..."}],
  "verdict": "approve|request-changes"
}

3. Aggregate Results

## Multi-Agent Verification Report

| Agent | Score | Verdict | Critical | Major | Minor |
|-------|-------|---------|----------|-------|-------|
| Code Quality | 85 | approve | 0 | 1 | 2 |
| Security | 95 | approve | 0 | 0 | 1 |
| Spec Alignment | 90 | approve | 0 | 1 | 0 |
| Architecture | 88 | approve | 0 | 1 | 1 |
| Code Simplifier | 92 | approve | 0 | 0 | 2 |
| Housekeeper | 90 | approve | 0 | 1 | 0 |
| Performance | 82 | approve | 0 | 1 | 1 |
| Design Consistency | 88 | approve | 0 | 1 | 1 |

4. Autonomous Fix-and-Retry Loop

Rule: You MUST continue this loop until ALL agents return approve. No exceptions. No user overrides.

On any request-changes verdict:

Log Iteration

## Verification Iteration [N]
| Agent | Verdict | Findings |
|-------|---------|----------|
| ... | ... | ... |
Fixing [X] issues...

Fix Each Finding - Apply each non-minor recommendation
- Track what was changed
- Note which finding each fix addresses
Re-run Self-Validation
- Verify action items still complete
- Run tests - must pass
- Confirm acceptance criteria
Re-run Agent Validation - Launch all 8 agents again
- Do NOT re-read updated files into the orchestrator context — agents will re-read the updated files themselves
- Only update changed_file_paths or diff_stat if the set of changed files has changed
Check Results
- ALL approve → PASS, return success
- Any request-changes → Return to step 1

5. Stuck Detection

Track findings by key: [Agent]-[Category]-[File]-[Line]

If same finding appears 3 times:

## Stuck - Need User Input

Issue persists after 3 attempts:

**[Agent] Finding description**
- File: path/to/file.ts
- Line: 42
- Attempts:
  1. [what was tried]
  2. [what was tried]
  3. [what was tried]

I need clarification: [specific question]

Use AskUserQuestion for guidance
Apply fix based on user input
Continue loop

Also escalate when:

Conflicting requirements between agents
Missing information to implement fix

6. Return Result

On PASS:

## Verification PASSED

All 8 agents approved after [N] iteration(s).

| Agent | Score | Verdict | Summary |
|-------|-------|---------|---------|
| ... | ... | APPROVE | ... |

Issues fixed:
- [Iteration N] Agent: Description

Minor suggestions (optional):
- ...

Return control to calling skill.

Severity Reference

Level	Action
critical	Must fix, loop continues
major	Must fix, loop continues
minor	Optional, does not block

validation-loop