Spec Completion Tracking System

Version: 1.1.0
Last Updated: 2026-02-24
Status: Active This guide explains how to use the spec completion tracking system to monitor implementation progress, track deferred phases, and generate completion reports. There are no separate commands for audit, status update, or complete-feature; use spec-complete with the flags below. Single command: All completion operations are performed via spec-complete (.cursor/commands/specs/spec-complete.md). The workflow names below (audit, status update, complete-with-deferred) describe what you are doing; they are implemented as sub-operations of spec-complete using the flags in the table. There are no separate audit-spec-completion, update-spec-status, or complete-feature command files—only spec-complete with the flags above.

Workflow (conceptual)	Use this
Comprehensive completion audit	`spec-complete --spec {CORE-##} --completion-report [--include-deferred] [--output path]`
Quick status update / update log	`spec-complete --spec {CORE-##} [--notes "…"]` (updates implementation log and status)
Complete feature with deferred checking	`spec-complete --spec {CORE-##} --check-deferred [--update-deferred-summary]`
Update status registry	`spec-complete --spec {CORE-##} --completion-report --update-registry`

Overview

The spec completion tracking system provides:

Automated Auditing: Comprehensive completion status checks for all specifications (via spec-complete --completion-report)
Deferred Phase Tracking: Monitor status of deferred phases and enhancements (spec-complete --check-deferred, --update-deferred-summary)
Status Registry: Centralized view of completion across all cores (spec-complete --update-registry)
Completion Reports: Detailed reports with recommendations and missing items (spec-complete --completion-report --output path)
Quick Status Updates: Fast status updates via spec-complete (updates implementation log and metadata)

Key Components

Command

spec-complete is the only completion command. Use the flags above to perform audits, status updates, and deferred checks.

Files

specs/SPEC_STATUS_REGISTRY.md - Centralized completion status
specs/{core}/IMPLEMENTATION_LOG.md - Detailed completion history
specs/{core}/summaries/DEFERRED-PHASES-SUMMARY.md - Deferred work tracking

Board and assignment tracking: For GitHub Project setup and when to update the board (whats-next, spec-complete, start work), see GITHUB_PROJECT_SPEC_TRACKING_PLAN.md.

Common Workflows

1. Audit a Single Spec

Use Case: Check completion status of a specific specification

# Basic audit (completion report)
spec-complete --spec HR-02 --completion-report

# Include deferred phases
spec-complete --spec HR-02 --completion-report --include-deferred

# Generate detailed report to file
spec-complete --spec HR-02 --completion-report --include-deferred --output reports/hr-02-completion.md

What It Does:

Reads spec file and implementation log
Checks code implementation (tables, hooks, components)
Validates test coverage
Checks deferred phases status
Generates completion report

Output:

Completion percentage breakdown
Phase-by-phase status
Missing items checklist
Recommendations

2. Quick Status Update

Use Case: Update status after completing a phase

# Update implementation log and spec status (with notes)
spec-complete --spec HR-02 --notes "Complete (Base + Enhancements 1-3)"

# Add completion notes
spec-complete --spec HR-02 --notes "Completed credential renewal workflow"

Note: Phase-level and percentage updates are reflected in the implementation log and spec metadata when you run spec-complete. For read-only status, use spec-status --spec HR-02 --detailed. What It Updates:

Spec file metadata
Implementation log entry
Status registry (if exists)

3. Complete Feature with Deferred Checking

Use Case: Mark feature complete and check deferred phases

# Complete with deferred checking
spec-complete --spec HR-02 --check-deferred

# Update deferred summary
spec-complete --spec HR-02 --update-deferred-summary

# Full completion with report
spec-complete --spec HR-02 --check-deferred --completion-report

What It Does:

Validates spec completion
Checks test coverage
Validates documentation
Checks deferred phases (if --check-deferred)
Updates implementation log
Generates report (if --completion-report)

4. Audit All Specs

Use Case: Get overview of all specs across all cores

# Audit all specs
spec-complete --completion-report --all --include-deferred

# Update status registry
spec-complete --completion-report --all --update-registry

# Generate reports for all
spec-complete --completion-report --all --include-deferred --output reports/all-specs-completion.md

What It Does:

Audits all specs in all cores
Calculates completion percentages
Updates status registry
Generates summary statistics

5. Audit Core-Specific Specs

Use Case: Focus on a specific core module

# Audit all HR specs
spec-complete --completion-report --core hr --include-deferred

# Update registry for HR core
spec-complete --completion-report --core hr --update-registry

# Re-verify LO and update registry only (script)
node scripts/audit/audit-spec-completion.js --core=lo --include-deferred --update-registry

Understanding Completion Status

Status Symbols

✅ Complete - Fully implemented and tested
🚧 In Progress - Currently being implemented
📋 Specification - Spec written, not started
📋 Deferred - Specified but not implemented
⏳ In Progress (Deferred) - Deferred phase being implemented

Completion Percentage Calculation

The system calculates two completion metrics:

Scope Completion (Primary Metric)

What percentage of the current planned scope is done. Does NOT include deferred phases.

Base Implementation: 60% weight
Enhancements: 40% weight

Example:

Base: 100% complete
Enhancements: 2 of 3 complete (67%)
Scope Completion: (100% × 0.6) + (67% × 0.4) = 87%

Full Completion (Secondary Metric)

What percentage of all specified work (including deferred) is done.

Scope Completion: 70% weight
Deferred Phases: 30% weight

Example:

Scope Completion: 87%
Deferred Phases: 0 of 2 complete (0%)
Full Completion: (87% × 0.7) + (0% × 0.3) = 61%

Interpretation: A spec with 100% Scope Completion is “done for now” even if deferred phases haven’t started. Full Completion shows overall progress toward complete feature parity.

Status Registry

The status registry (specs/SPEC_STATUS_REGISTRY.md) provides a centralized view of all specs.

Viewing the Registry

# Open the registry file
cat specs/SPEC_STATUS_REGISTRY.md

# Or view in your editor

Updating the Registry

# Auto-update after auditing
spec-complete --completion-report --all --update-registry

# Update specific core
spec-complete --completion-report --core hr --update-registry

Registry Structure

The registry includes:

Summary statistics by core
Table for each core with:
- Spec ID and name
- Base status
- Enhancements status
- Deferred phases count
- Overall completion percentage
- Last audited date

Completion Reports

Report Structure

Completion reports include:

Summary Section
- Overall status
- Completion percentage
- Last audited date
Base Implementation
- Status and completion date
- Implementation log link
- Test coverage summary
Enhancements
- Status of each enhancement
- Completion dates
Deferred Phases
- Status of each deferred phase
- Expansion spec links
- Implementation status
- Estimated effort
Missing Items
- Checklist of incomplete items
- Test coverage gaps
- Documentation gaps
Recommendations
- Next steps
- Priority items
- Estimated effort

Generating Reports

# Generate report for specific spec
spec-complete --completion-report --spec HR-02 --include-deferred --output reports/hr-02-completion.md

# Generate report for all specs
spec-complete --completion-report --all --include-deferred --output reports/all-specs-completion-2026-01-03.md

Best Practices

1. Regular Audits

Frequency:

Weekly: For active development cores (HR, RH, FA)
Monthly: For all cores to track overall progress
Before Planning: Run before planning new work
After Major Completions: Run after completing major features

# Weekly audit for active core
spec-complete --completion-report --core hr --include-deferred --update-registry

# Monthly full audit
spec-complete --completion-report --all --include-deferred --update-registry

2. Incremental Status Updates

Update status as you complete phases, not just at the end:

# After completing base implementation
spec-complete --spec HR-02 --notes "Complete (Base)" 

# After completing enhancements
spec-complete --spec HR-02 --notes "Complete (Base + Enhancements)"

# After completing deferred phases
spec-complete --spec HR-02 --notes "Complete"

3. Deferred Phase Tracking

Keep deferred phases up to date:

# Check deferred phases when completing features
spec-complete --spec HR-02 --check-deferred

# Update deferred summary
spec-complete --spec HR-02 --update-deferred-summary

4. Report Generation

Save reports for historical tracking:

# Generate dated reports
spec-complete --completion-report --spec HR-02 --output reports/hr-02-completion-$(date +%Y-%m-%d).md

# Generate quarterly reports
spec-complete --completion-report --all --output reports/q1-2026-completion.md

5. Status Registry Maintenance

Keep the registry current:

# Update after major changes
spec-complete --completion-report --all --update-registry

# Update specific core regularly
spec-complete --completion-report --core hr --update-registry

Integration with Other Commands

With `validate-spec`

# Validate spec structure first
validate-spec --spec HR-02

# Then audit completion
spec-complete --completion-report --spec HR-02

With `check-coverage`

# Check test coverage
check-coverage --module hr

# Audit completion (includes coverage check)
spec-complete --completion-report --spec HR-02

With `spec-complete`

# Complete feature with full validation
spec-complete --spec HR-02 --check-deferred --completion-report

# Combines deferred-phase check and full completion audit in one pass

Troubleshooting

Status Not Updating

Problem: Status updates not reflected in registry Solution:

# Manually update registry
spec-complete --completion-report --spec HR-02 --update-registry

Missing Deferred Phases

Problem: Deferred phases not showing in audit Solution:

# Use --include-deferred flag
spec-complete --completion-report --spec HR-02 --include-deferred

Incorrect Completion Percentage

Problem: Completion percentage seems wrong Solution:

# Run full audit to recalculate
spec-complete --completion-report --spec HR-02 --include-deferred

# Check implementation log for accuracy
cat specs/hr/IMPLEMENTATION_LOG.md

Examples

Example 1: New Feature Completion

# 1. Implement feature
# ... implementation work ...

# 2. Update status after base implementation
spec-complete --spec HR-10 --notes "Complete (Base)"

# 3. Complete feature with validation
spec-complete --spec HR-10 --check-deferred

# 4. Generate final report
spec-complete --completion-report --spec HR-10 --include-deferred --output reports/hr-10-completion.md

Example 2: Deferred Phase Implementation

# 1. Audit to see deferred phases
spec-complete --completion-report --spec HR-02 --include-deferred

# 2. Implement deferred phase
# ... implementation work ...

# 3. Update status
spec-complete --spec HR-02 --notes "Phase 2: External Verification complete"

# 4. Update deferred summary
spec-complete --spec HR-02 --update-deferred-summary

# 5. Re-audit
spec-complete --completion-report --spec HR-02 --include-deferred

Example 3: Monthly Progress Review

# 1. Audit all specs
spec-complete --completion-report --all --include-deferred --update-registry

# 2. Generate summary report
spec-complete --completion-report --all --include-deferred --output reports/monthly-progress-2026-01.md

# 3. Review status registry
cat specs/SPEC_STATUS_REGISTRY.md

Commands: .cursor/README.md - All cursor commands
Status Registry: specs/SPEC_STATUS_REGISTRY.md - Centralized completion tracking
Implementation Logs: specs/{core}/IMPLEMENTATION_LOG.md - Detailed completion history
Deferred Phases: specs/{core}/summaries/DEFERRED-PHASES-SUMMARY.md - Deferred work tracking
Spec Template: specs/_templates/SPEC_TEMPLATE.md - Completion status format

Quarterly Deferred Review Process

Every quarter, perform a comprehensive review of deferred phases to ensure specifications stay current and priorities are aligned.

Quarterly Review Checklist

# Step 1: Generate comprehensive report
spec-complete --completion-report --all --include-deferred --output reports/deferred-review-Q{Q}-{YYYY}.md

# Step 2: Sync all deferred summaries
spec deferred --sync

# Step 3: Update registry
spec-complete --completion-report --all --update-registry

Review Questions

For each deferred phase, answer:

Still Relevant?
- Business need still exists
- Technical approach still valid
- Not superseded by other features
Dependencies Changed?
- Check all dependency statuses
- Identify newly available dependencies
- Update blocked/ready status
Priority Adjustment?
- Review with stakeholders
- Update priority if needed
- Consider promoting to active scope
Effort Estimate Valid?
- Technology changes may affect estimate
- Team capacity changes
- Update estimates if >20% different

Actions After Review

Finding	Action
Feature no longer needed	Run `spec deferred --promote --spec X --feature Y` with cancellation
Dependencies now available	Move to “Ready for Implementation”
Priority increased	Consider promoting to active scope
Estimate significantly changed	Update expansion spec
Specification outdated	Update expansion spec or create new one

Review Schedule

Quarter	Review Date	Report Location
Q1	First week of January	`reports/deferred-review-Q1-{YYYY}.md`
Q2	First week of April	`reports/deferred-review-Q2-{YYYY}.md`
Q3	First week of July	`reports/deferred-review-Q3-{YYYY}.md`
Q4	First week of October	`reports/deferred-review-Q4-{YYYY}.md`

Review Meeting Template

# Deferred Phases Quarterly Review - Q{Q} {YYYY}

**Date:** {date}
**Attendees:** {list}

## Summary
- Total deferred phases: {N}
- Ready for implementation: {N}
- Blocked: {N}
- Cancelled this quarter: {N}
- Promoted this quarter: {N}

## Actions
| Spec | Phase | Decision | Owner | Due |
|------|-------|----------|-------|-----|
| | | | | |

## Next Quarter Focus
- {Priority 1}
- {Priority 2}

Last Updated: 2026-01-03
Next Review: After first month of usage

Architecture

Development

Database

Testing

Migration

Operations

Governance & Security

Platform Internals

Documentation Index

​Overview

​Key Components

​Command

​Files

​Common Workflows

​1. Audit a Single Spec

​2. Quick Status Update

​3. Complete Feature with Deferred Checking

​4. Audit All Specs

​5. Audit Core-Specific Specs

​Understanding Completion Status

​Status Symbols

​Completion Percentage Calculation

​Scope Completion (Primary Metric)

​Full Completion (Secondary Metric)

​Status Registry

​Viewing the Registry

​Updating the Registry

​Registry Structure

​Completion Reports

​Report Structure

​Generating Reports

​Best Practices

​1. Regular Audits

​2. Incremental Status Updates

​3. Deferred Phase Tracking

​4. Report Generation

​5. Status Registry Maintenance

​Integration with Other Commands

​With validate-spec

​With check-coverage

​With spec-complete

​Troubleshooting

​Status Not Updating

​Missing Deferred Phases

​Incorrect Completion Percentage

​Examples

​Example 1: New Feature Completion

​Example 2: Deferred Phase Implementation

​Example 3: Monthly Progress Review

​Related Documentation

​Quarterly Deferred Review Process

​Quarterly Review Checklist

​Review Questions

​Actions After Review

​Review Schedule

​Review Meeting Template

Overview

Key Components

Command

Files

Common Workflows

1. Audit a Single Spec

2. Quick Status Update

3. Complete Feature with Deferred Checking

4. Audit All Specs

5. Audit Core-Specific Specs

Understanding Completion Status

Status Symbols

Completion Percentage Calculation

Scope Completion (Primary Metric)

Full Completion (Secondary Metric)

Status Registry

Viewing the Registry

Updating the Registry

Registry Structure

Completion Reports

Report Structure

Generating Reports

Best Practices

1. Regular Audits

2. Incremental Status Updates

3. Deferred Phase Tracking

4. Report Generation

5. Status Registry Maintenance

Integration with Other Commands

With `validate-spec`

With `check-coverage`

With `spec-complete`

Troubleshooting

Status Not Updating

Missing Deferred Phases

Incorrect Completion Percentage

Examples

Example 1: New Feature Completion

Example 2: Deferred Phase Implementation

Example 3: Monthly Progress Review

Related Documentation

Quarterly Deferred Review Process

Quarterly Review Checklist

Review Questions

Actions After Review

Review Schedule

Review Meeting Template