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(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(Partially Grounded)	50-79%	Evidence exists but requires clarification	⚠️ Verify before implementation
🔴 Missing(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

speckit-task-grounding