SpecKit Task Grounding Validator Skill

SpecKit Task Grounding Validator

A framework for validating that development tasks are properly grounded in planning artifacts before implementation, enabling parallel task validation and reducing implementation risks.

Integration with Speckit SDD

This skill integrates with the Spec-Driven Development (SDD) methodology implemented by Speckit:

SDD Workflow: specify → plan → tasks
Artifact Scope: Works within specs/[branch-name]/ specification folders
Validation Timing: Use after /speckit.tasks generates the task list
Quality Gate: Ensures tasks are properly grounded before implementation begins

Core Concept

Parallel Task Validation: Each task grounding check is independent, allowing multiple reviewers to validate tasks simultaneously (2-3 minutes per task).

Quick Start

Verify artifacts exist: Check for spec.md, plan.md, tasks.md, and supporting artifacts
Process each task in parallel:
- Extract task details from tasks.md
- Search artifacts for evidence
- Score grounding level (0-100%)
- Assess risk and identify gaps
- Document findings
Generate report: Use the complete report template for decision gates

Grounding Score Calculator

| Score | Meaning | Evidence Required | Action | | -------- | ---------- | ------------------------------------ | ---------------- | | 100% | Explicit | Direct quote with exact location | ✅ Execute | | 90% | Detailed | Code example or schema provided | ✅ Execute | | 80% | Referenced | Clear spec with implementation notes | ✅ Execute | | 70% | Pattern | Documented pattern to follow | ⚠️ Verify pattern | | 60% | Inferred | Multiple weak references | ⚠️ Clarify | | 50% | Assumed | Single weak reference | 🔴 High risk | | <50% | Missing | No evidence found | 🔴 Block |

Decision Matrix

Phase Thresholds

Phase 1 (Setup): ≥90% tasks at ≥80% grounding
Phase 2 (Foundation): ≥80% tasks at ≥70% grounding
Phase 3+ (Features): ≥70% tasks at ≥60% grounding

Risk Levels

🟢 Low: ≥90% grounding, no gaps
🟡 Medium: 70-89% grounding, resolvable gaps
🔴 High: <70% grounding, critical gaps

📚 Grounding Status Glossary

Task Grounding Status Values

| Status | Meaning | Description | Action | | --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | | 🟢 Documented<br/>(Fully Grounded) | 80-100% | Clear specification with implementation details from planning phase artifacts (plan.md, research.md, data-model.md, contracts/, quickstart.md) | ✅ Ready to implement | | 🟡 Inferred<br/>(Partially Grounded) | 50-79% | Evidence exists but requires clarification | ⚠️ Verify before implementation | | 🔴 Missing<br/>(Ungrounded) | <50% | No evidence found in artifacts | 🔴 Block until specified |

Phase-Level Grounding Status Values

| Status | Meaning | Description | | ------------------------ | --------------------------- | -------------------------------------------- | | 🟢 Fully Documented | ≥80% tasks fully grounded | All critical tasks have clear specifications | | 🟢 Mostly Documented | 70-79% tasks fully grounded | Most tasks grounded, minor gaps | | 🟡 Partially Inferred | 50-69% tasks fully grounded | Significant gaps requiring clarification | | 🟡 Mostly Inferred | 30-49% tasks fully grounded | Major gaps, high risk | | 🔴 Poorly Grounded | <30% tasks fully grounded | Critical gaps, block implementation |

Risk Level Values

| Level | Meaning | Description | | ------------ | --------------------------------- | -------------------------------------- | | 🟢 Low | ≥90% grounding, no gaps | Straightforward implementation | | 🟡 Medium | 70-89% grounding, resolvable gaps | Needs verification but implementable | | 🔴 High | <70% grounding, critical gaps | High risk, may require planning rework |

Overall Assessment Values

| Assessment | Meaning | Description | | ------------------------- | --------------------------------------- | ------------------------------ | | ✅ APPROVE | Meets phase thresholds | Proceed with implementation | | ⚠️ NEEDS CLARIFICATION | Resolvable gaps identified | Address gaps before proceeding | | 🔴 BLOCK | Critical gaps or insufficient grounding | Return to planning phase |

Grounding Score Scale (0-100%)

| Score | Qualitative Term | Evidence Required | | -------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------- | | 100% | Explicit | Direct quote with exact location from planning phase artifacts | | 90% | Detailed | Code example or schema provided from planning phase artifacts | | 80% | Referenced | Clear implementation details from planning phase artifacts (plan.md, research.md, data-model.md, contracts/, quickstart.md) | | 70% | Pattern | Documented pattern to follow from any artifact | | 60% | Inferred | Multiple weak references from any artifacts | | 50% | Assumed | Single weak reference from any artifact | | <50% | Missing | No evidence found in any artifacts (spec.md alone does not qualify for ≥80% scores) |

Important: Tasks must be grounded in planning phase artifacts to achieve "Documented" (≥80%) status. Evidence from spec.md alone caps scoring at 70% maximum, as spec.md represents requirements specification rather than implementation planning.

Key Features

Parallel Processing: Independent task validation enables team distribution
Evidence-Based Scoring: Systematic 0-100% grounding assessment
Gap Analysis: Identifies missing specifications with resolution steps
Decision Gates: Clear approve/clarify/block recommendations
Report Templates: Complete documentation framework

Usage Workflow

For each task in tasks.md:

Extract task details and requirements
Exhaustively search ALL artifacts in order: spec.md → plan.md → research.md → data-model.md → contracts/ → quickstart.md (do not stop at first evidence found - scan all artifacts for complete grounding assessment)
Score grounding level based on evidence strength
Assess risk and document gaps
Aggregate results for feature-level decision

Parallel Processing Workflow

Step 1: Assign Tasks to Reviewers

Reviewer A: Tasks T001-T003 (Phase 1)
Reviewer B: Tasks T004-T005 (Phase 2)
Reviewer C: Tasks T006+ (Phase 3+)

Step 2: Individual Validation

# Reviewer A validates their assigned tasks
.\scripts\Validate-TaskGrounding.ps1 -FeaturePath "specs/my-feature" -TaskFilter "T001,T002,T003" -JsonOutput -OutputPath "specs/my-feature/assessments/reviewerA-assessment.json"

# Reviewer B validates their assigned tasks
.\scripts\Validate-TaskGrounding.ps1 -FeaturePath "specs/my-feature" -TaskFilter "T004,T005" -JsonOutput -OutputPath "specs/my-feature/assessments/reviewerB-assessment.json"

Step 3: Aggregate Results

# Combine all individual assessments into final report
.\scripts\Aggregate-TaskGrounding.ps1 -FeatureName "my-feature" -AssessmentFiles @("specs/my-feature/assessments/reviewerA-assessment.json", "specs/my-feature/assessments/reviewerB-assessment.json", "specs/my-feature/assessments/reviewerC-assessment.json") -OutputPath "specs/my-feature/tasks.grounding.md"

Post-Aggregation Cleanup:

# Optional: Remove intermediate assessment files after successful aggregation
Remove-Item "specs/my-feature/assessments/*.json"

Benefits:

Parallel Execution: 2-3 minutes per reviewer instead of 15-25 minutes total
Independent Validation: Each task assessed by one person, avoiding conflicts
Efficient Aggregation: Automated combination maintains consistency
Scalable: Works with 2 reviewers or 10 reviewers equally well

Resulting File Structure

After complete validation, your specification folder will contain:

specs/[branch-name]/
├── spec.md                    # Original artifacts
├── plan.md
├── research.md
├── data-model.md
├── contracts/
├── quickstart.md
├── tasks.md
├── assessments/                # Intermediate files (can be removed after aggregation)
│   ├── reviewerA-assessment.json
│   ├── reviewerB-assessment.json
│   └── reviewerC-assessment.json
└── tasks.grounding.md         # Final validation report (VS Code nested under tasks.md)

References

Complete Framework - Full validation methodology and templates
Scoring Examples - Real-world validation cases
Report Template - Reusable template for validation reports
Report Example - Complete filled-out validation report
Automation Scripts - PowerShell validation and aggregation scripts

Prerequisites

spec.md - Feature specification with user stories and requirements (highest authority)
plan.md - Implementation plan with technical decisions
research.md - Technical research and context gathering
data-model.md - Data models and entity definitions
contracts/ - Directory containing API contracts and interface specifications
quickstart.md - Key validation scenarios and quickstart guide
tasks.md - Executable task list derived from plan (input for validation)
assessments/ - Directory for intermediate assessment files (created automatically)

Common Use Cases

Feature Readiness: Validate all tasks before implementation begins
Specification Review: Ensure planning artifacts are complete
Risk Assessment: Identify implementation uncertainties early
Team Coordination: Parallel validation by multiple reviewers
Quality Gates: Automated checking in CI/CD pipelines
SDD Compliance: Validate Speckit-generated artifacts meet grounding standards

Output

File Locations (relative to specification root):

assessments/reviewer*-assessment.json - Individual reviewer assessments (intermediate files)
tasks.grounding.md - Final comprehensive validation report

Report Contents:

Executive Summary table with phase status
Task Grounding Matrix with status indicators
Gap analysis with impact and resolution steps
Action plan with phase-specific execution steps
Risk assessment and mitigation strategies
Decision gate recommendation (Approve/Clarify/Block)

Decision Rules

✅ APPROVE: Meets phase thresholds, no critical gaps
⚠️ CLARIFY: Resolvable gaps identified, needs verification
🔴 BLOCK: Critical gaps or insufficient grounding

Training Levels

Level 1 (30 min): Basic scoring and validation process
Level 2 (60 min): Complex cases and customization
Level 3 (2 hours): Administration and team training

Version History

v3 (Current): Single-page parallel validation framework
v2 (Experimental): Four-file compressed structure
v1 (Experimental): Original 13-file comprehensive documentation

Agent Skills: SpecKit Task Grounding Validator

Install this agent skill to your local

Skill Files