Validate Backlog.md Structure

Audit the backlog directory for naming violations, structural issues, and metadata inconsistencies.

Instructions

Launch the backlog-validator agent to perform comprehensive validation:

Use the backlog-validator agent to:
1. Check all task files match the `task-{id} - {title}.md` pattern
2. Verify CLI can read all task files
3. Detect orphaned or malformed files
4. Identify metadata inconsistencies
5. Generate a comprehensive validation report
6. Recommend remediation steps for any issues found

The validator will perform these checks:

Validation Scope

Critical Checks (Block Functionality)

File Naming Pattern: All files match task-{id} - {title}.md
CLI Accessibility: Can backlog task list see all files?
Directory Structure: Required directories exist
Task ID Integrity: No duplicate or missing IDs

Warning Checks (Impact Workflow)

Task Completeness: Missing acceptance criteria or descriptions
Workflow Issues: Stale "In Progress" tasks, Done tasks with unchecked ACs
Metadata Quality: Tasks without assignees, missing priorities

Info Checks (Project Health)

Status Distribution: How tasks are distributed across To Do/In Progress/Done
Label Usage: Which labels are most common
Assignee Workload: How work is distributed across team

Expected Output

The validator will generate a report like:

# Backlog.md Validation Report

## Executive Summary
- 📁 Total Files: 47
- ✅ Valid Tasks: 45
- ❌ Violations: 2
- 🏥 Health Score: 95%

## Critical Issues

### Naming Violations
❌ task-23-Fix bug.md
   Expected: task-23 - Fix bug.md
   Issue: Missing spaces around separator

❌ Fix login issue.md
   Expected: task-{id} - Fix login issue.md
   Issue: Missing task ID prefix

## Warnings

### Incomplete Tasks
⚠️  task-15 - Add API endpoint.md
   Missing acceptance criteria

⚠️  task-28 - Refactor components.md
   Status "In Progress" but no recent activity (14 days)

## Recommendations

### Immediate Fixes
1. Fix naming for task-23:
   backlog task edit 23 -t "Fix bug"
   (CLI will update filename automatically)

2. Recreate orphaned task:
   backlog task create "Fix login issue" -d "..."

3. Add ACs to task-15:
   backlog task edit 15 --ac "First criterion"

## Project Health
- To Do: 12 (26%)
- In Progress: 8 (17%)
- Done: 27 (57%)

When to Run Validation

Use this command when:

Troubleshooting Issues:
- "Task not showing up in list"
- "CLI can't find task"
- "Board not displaying correctly"
After Bulk Operations:
- Created multiple tasks
- Imported tasks from other systems
- Reorganized backlog structure
Periodic Health Checks:
- Weekly validation recommended
- Before major milestones
- After team onboarding
Quality Assurance:
- Ensuring naming compliance
- Checking workflow state health
- Validating metadata quality

What Gets Validated

File Naming Pattern

Valid:   task-42 - Add authentication.md
Invalid: task-42-Add authentication.md
Invalid: 42 - Add authentication.md
Invalid: task-42.md

Directory Structure

Required:
- backlog/tasks/     (all task files)
- backlog/docs/      (documentation)
- backlog/decisions/ (ADRs)
- backlog/drafts/    (draft tasks)

Task Metadata

Frontmatter exists and is valid YAML
Required fields present (id, title, status)
Status values are valid
Task ID matches filename

Important Notes

Non-destructive: Validation never modifies files
Comprehensive: Checks multiple layers (naming, metadata, workflow)
Actionable: Provides specific CLI commands to fix issues
Educational: Explains why violations matter

After Validation

If issues are found:

Review the report with the user
Prioritize fixes: Critical > Warning > Info
Offer to help fix issues using proper CLI commands
Educate on prevention (use hooks, use agents)
Run validation again after fixes to confirm

Definition of Done for This Command

backlog-validator agent launched
Comprehensive validation performed
Report generated and presented to user
Issues categorized by severity
Remediation commands provided for all issues
User understands how to prevent future violations

4.3 KiB Raw Permalink Blame History