Help us improve
Share bugs, ideas, or general feedback.
From humaninloop
Reviews planning artifacts like requirements, data models, API contracts for gaps in analysis and design phases. Classifies issues by severity for quality gates before proceeding.
npx claudepluginhub joshuarweaver/cascade-ai-ml-agents-agent-framework --plugin deepeshbodh-human-in-loopHow this skill is triggered — by the user, by Claude, or both
Slash command
/humaninloop:validation-plan-artifactsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Find gaps in planning artifacts and generate issues that need resolution before proceeding. Focus on design completeness and quality, not implementation details. This skill provides phase-specific review criteria for artifact reviewers.
Reviews design artifacts (proposals, specs, designs, tasks) for internal consistency, gaps, and cross-artifact alignment before implementation.
Validates design documents before planning. Uses a 9-point checklist to catch specification gaps and assess architecture, test strategy, and handoff quality.
Validates implementation plans against requirements and design documents, flagging missing coverage, ambiguities, and design divergences.
Share bugs, ideas, or general feedback.
Find gaps in planning artifacts and generate issues that need resolution before proceeding. Focus on design completeness and quality, not implementation details. This skill provides phase-specific review criteria for artifact reviewers.
Violating the letter of the rules is violating the spirit of the rules.
humaninloop:validation-task-artifacts insteadhumaninloop:analysis-specifications insteadhumaninloop:validation-constitution insteadEach phase has specific checks to execute. The checks identify Critical, Important, and Minor issues.
| Phase | Focus Area | Key Checks |
|---|---|---|
| A0 | Codebase Discovery | Coverage, entity/endpoint detection, collision assessment |
| P1 | Analysis | FR coverage, orphan TRs, testable criteria, sourced constraints, decision alternatives, NFR measurability |
| P2 | Design | Entity coverage, relationships, data sensitivity, endpoint coverage, schemas, error handling, integration boundaries |
| P3 | Cross-Artifact | Alignment, consistency, traceability |
See PHASE-CHECKLISTS.md for detailed phase-specific checklists and key questions.
Issues are classified by severity to determine appropriate action:
| Severity | Definition | Action |
|---|---|---|
| Critical | Blocks progress; must resolve | Return to responsible agent |
| Important | Significant gap; should resolve | Flag for this iteration |
| Minor | Polish item; can defer | Note for later |
See ISSUE-TEMPLATES.md for severity classification rules, issue documentation formats, and report templates.
Read and understand:
For each check in the phase-specific checklist:
For Phase P2 (Design), use incremental review to optimize time while preserving rigor.
## Review Summary
| Aspect | Status |
|--------|--------|
| **New Artifacts** | {artifacts} - FULL REVIEW |
| **Previous Artifacts** | CONSISTENCY CHECK ONLY |
## New Artifact Issues
{Full issue documentation with evidence}
## Cross-Artifact Consistency
| Check | Status | Notes |
|-------|--------|-------|
| Entity names match TRs | Pass/Fail | {any mismatches} |
| Schemas match data model | Pass/Fail | {any gaps} |
| Decisions honored in design | Pass/Fail | {any contradictions} |
| Sensitivity annotations present | Pass/Fail | {any missing} |
| Integration boundaries documented | Pass/Fail | {any missing} |
## Verdict
{ready / needs-revision / critical-gaps}
| Phase | Full Review | Consistency Check |
|---|---|---|
| P1 (Analysis) | requirements.md, constraints-and-decisions.md, nfrs.md | — (first phase) |
| P2 (Design) | data-model.md, contracts/api.yaml, quickstart.md | requirements.md + constraints-and-decisions.md + nfrs.md (2-3 min) |
| Verdict | Criteria |
|---|---|
| ready | Zero Critical, zero Important issues |
| needs-revision | 1-3 Important issues, fixable in one iteration |
| critical-gaps | 1+ Critical or 4+ Important issues |
Before finalizing review, verify:
❌ Marking style issues as "Critical" ✅ Reserve Critical for issues that genuinely block progress
❌ "The data model is incomplete" ✅ "The data model is missing the User entity referenced in FR-003"
❌ "Fix the contracts" ✅ "Add error response schema for 404 case in GET /users/{id}"
❌ Commenting on code patterns, variable names, or framework choices ✅ Focus on design completeness, traceability, and consistency
❌ Reviewing only the new artifact in isolation ✅ Always verify consistency with previous phase artifacts
❌ Re-reading all previous artifacts in full for every review ✅ Use incremental review mode with targeted consistency checks
If you notice yourself thinking any of these, STOP immediately:
| Rationalization | Counter |
|---|---|
| "The spec was vague, so the artifact can be vague" | Vagueness in spec is a gap to flag, not permission to propagate. |
| "This is a minor feature, full review is overkill" | Scale of feature does not change the review process. Every artifact gets every applicable check. |
| "Time pressure means we should skip cross-artifact checks" | Cross-artifact inconsistencies caught now save days of rework later. |
| "The author is senior, they know what they're doing" | Author seniority is irrelevant. Evidence-based review only. |
| "I already found enough issues" | Finding issues is not a quota. Run every check, document every finding. |
| "This check doesn't apply to this type of feature" | If the check is in the phase checklist, it applies. Flag as N/A with justification if genuinely inapplicable. |
| "The constraint is obvious, it doesn't need documentation" | Obvious constraints are the ones most often violated. Document them. |