Master Plan Auditor

Master Plan Auditor

Read-only analysis of MASTER_PLAN.md and beads issues. Provides recommendations with confidence scores.

Philosophy: User confirmation = done. Tests passing and commits existing are evidence, not proof.

Quick Start

/audit-tasks

Features

Workflow

Step 1: Parse MASTER_PLAN.md

Read docs/MASTER_PLAN.md and extract all tasks with their statuses from all 3 locations.

Location Detection Patterns

Location 1: Summary Table

| **TASK-XXX** | Feature Name | Priority | 🔄 **IN PROGRESS** | ... |
| ~~**TASK-XXX**~~ | ✅ **DONE** Feature Name | Priority | ✅ **DONE** (date) | ... |

Regex pattern:

\| \*\*(?:~~)?(?<id>TASK-\d+|BUG-\d+|ISSUE-\d+|ROAD-\d+|IDEA-\d+)(?:~~)?\*\* \|

Location 2: Subtasks/Bullet Lists

- TASK-XXX: Description
- ~~TASK-XXX~~: ✅ Description (completed)

Regex pattern:

^[-*] (?:~~)?(?<id>TASK-\d+|BUG-\d+|ISSUE-\d+|ROAD-\d+|IDEA-\d+)(?:~~)?:

Location 3: Detailed Section Headers

#### TASK-XXX: Title (🔄 IN PROGRESS)
#### ~~TASK-XXX~~: Title (✅ DONE)

Regex pattern:

^#{3,4} (?:~~)?(?<id>TASK-\d+|BUG-\d+|ISSUE-\d+|ROAD-\d+|IDEA-\d+)(?:~~)?:.*\((?<status>[^)]+)\)

Status Detection (Priority Order)

Step 2: Gather Evidence for IN_PROGRESS Tasks

For each task that is NOT done:

# Count commits mentioning task
git log --oneline --all --grep="TASK-XXX" | wc -l

# Get last activity date
git log -1 --format=%ci --all --grep="TASK-XXX" 2>/dev/null || echo "never"

# Check for completion keywords in recent commits
git log --oneline --all --grep="TASK-XXX" | head -5 | grep -iE "(fix|implement|complete|done|finish|close)" || true

# Check if related tests exist
grep -r "TASK-XXX\|$(echo 'Feature keywords')" tests/ src/ --include="*.spec.ts" --include="*.test.ts" -l 2>/dev/null | head -3

Step 3: Calculate Confidence Scores

Confidence Score (0-100) - Higher = more likely done:

Interpretation:

• 70-100: Likely done (recommend verification)
• 40-69: Possibly done (needs investigation)
• 0-39: Still in progress

Step 4: Check Status Sync Across Locations

Compare status in all 3 locations for each task:

# Get all occurrences of a task ID
grep -n "TASK-XXX" docs/MASTER_PLAN.md

Mismatch examples:

• Table says 🔄 IN PROGRESS but header says (✅ DONE)
• ID has ~~strikethrough~~ but status column says PLANNED
• Bullet says ✅ but detailed section says PAUSED

Step 5: Detect Stale Tasks

Tasks with no git activity for 7+ days:

# Get days since last activity
last_commit=$(git log -1 --format=%ct --all --grep="TASK-XXX" 2>/dev/null)
now=$(date +%s)
days_ago=$(( (now - last_commit) / 86400 ))

if [ $days_ago -gt 7 ]; then
  echo "STALE: TASK-XXX - $days_ago days since last activity"
fi

Step 6: Cross-Reference Beads

# List all open beads issues
bd list --status=open 2>/dev/null || echo "Beads not available"

# List closed beads issues
bd list --status=closed 2>/dev/null || echo "Beads not available"

# Compare with MASTER_PLAN status

Mismatch Types:

• Beads OPEN + MASTER_PLAN DONE = "Beads issue should be closed"
• Beads CLOSED + MASTER_PLAN IN_PROGRESS = "Task may be done"

Graceful Degradation: If beads returns an error (repo ID mismatch, not initialized), output:

⚠️ Beads unavailable: [error message]
Skipping beads cross-reference. Other checks continue.

Step 7: Find Orphan Task IDs

Task IDs mentioned in git but not in MASTER_PLAN.md:

# Get all task IDs from git history
git log --oneline --all | grep -oE "(TASK|BUG|ISSUE|ROAD|IDEA)-[0-9]+" | sort -u > /tmp/git-tasks.txt

# Get all task IDs from MASTER_PLAN.md
grep -oE "(TASK|BUG|ISSUE|ROAD|IDEA)-[0-9]+" docs/MASTER_PLAN.md | sort -u > /tmp/plan-tasks.txt

# Find orphans (in git but not in plan)
comm -23 /tmp/git-tasks.txt /tmp/plan-tasks.txt

Output Report Format

# Task Audit Report

**Generated**: [timestamp]
**MASTER_PLAN.md**: docs/MASTER_PLAN.md
**Beads Status**: [Available/Unavailable]

## Summary

| Category | Count |
|----------|-------|
| Likely Done (needs verification) | X |
| Still In Progress | X |
| Stale (>7 days) | X |
| Status Inconsistencies | X |
| Beads Mismatches | X |
| Orphan IDs | X |

---

## Likely Done (Confidence ≥70)

These tasks have strong evidence of completion. **User verification required.**

### TASK-XXX: [Title]

| Metric | Value |
|--------|-------|
| Confidence | 85/100 |
| Last Activity | 2 days ago |
| Commits | 5 |
| Beads | Closed |

**Evidence:**
- Commit `abc123`: "fix: implement TASK-XXX feature complete"
- Tests exist: `tests/feature.spec.ts`
- Beads issue #42 closed on 2026-01-23

**To mark done:**
```bash
# Update all 3 locations in MASTER_PLAN.md:
# 1. Table: | ~~**TASK-XXX**~~ | ✅ **DONE** ... |
# 2. Bullet: - ~~TASK-XXX~~: ✅ ...
# 3. Header: #### ~~TASK-XXX~~: ... (✅ DONE)

# Then close beads (if open):
bd close [beads-id]

Still In Progress

These tasks show ongoing work.

TASK-YYY: [Title]

Recent commits:

• def456: "wip: TASK-YYY initial setup"

Stale Tasks (>7 Days)

No git activity detected. Consider: resume, pause, or mark done.

Recommendations:

• Resume work → update status to 🔄 IN PROGRESS
• Pause → update status to ⏸️ PAUSED
• Already done → verify with user, then mark ✅ DONE

Status Inconsistencies

These tasks have different statuses in different locations.

TASK-AAA

Fix: Update line 45 to match line 312 (or vice versa).

Beads Mismatches

MASTER_PLAN.md and beads show different statuses.

Orphan Task IDs

Found in git history but not in MASTER_PLAN.md.

Next Steps

1. Verify likely-done tasks with user, then run /done TASK-XXX
2. Fix inconsistencies by updating all 3 locations
3. Sync beads with bd close commands shown above
4. Resume or close stale tasks based on project priorities

---

## Important Rules

1. **NEVER auto-mark tasks as done** - Only provide recommendations
2. **User confirmation is required** - Tests/commits are evidence, not proof
3. **Check all 3 locations** - Table, bullets, detailed headers
4. **Graceful degradation** - If beads fails, continue with other checks
5. **Confidence scores guide priority** - High confidence = verify first

---

## Stale Threshold Configuration

Default: 7 days

The stale threshold can be mentioned in the audit request:

/audit-tasks --stale-days=14

---

## Integration with Other Skills

| Skill | How Auditor Relates |
|-------|---------------------|
| `/done` | Auditor recommends, `/done` executes the marking |
| `/dev-maestro` | Both parse MASTER_PLAN.md, use same patterns |
| `/smart-doc-manager` | For MASTER_PLAN.md structural updates |

---

## Troubleshooting

### Beads Error: "repo ID mismatch"

⚠️ Beads unavailable: Repository ID mismatch

This means the beads database was created for a different repo. The auditor will skip beads cross-reference and continue with other checks.

### No Git History for Task

If a task has no commits mentioning it:
- Confidence: 0
- Status: Based on MASTER_PLAN.md text only
- Recommendation: Verify manually

### Parser Missed a Task

If a task exists but wasn't found:
- Check the section header format
- Ensure task ID format matches: `TASK-XXX`, `BUG-XXX`, etc.
- Verify the section is a recognized type (Roadmap, Active Work, etc.)