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

| Feature | Description | |---------|-------------| | IN_PROGRESS Analysis | Parse all IN_PROGRESS tasks, gather git/test evidence, calculate confidence score | | Status Sync Checker | Verify all 3 MASTER_PLAN.md locations match (table, header, status line) | | Stale Task Detector | Flag tasks with no git activity for 7+ days | | Beads Cross-Reference | Compare MASTER_PLAN.md vs beads issues, find mismatches | | Orphan Finder | Task IDs in git/code but not in MASTER_PLAN.md |

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)

| Pattern | Detected Status | |---------|-----------------| | ~~ wrapping ID | done | | DONE, FIXED, COMPLETE, ✅ | done | | REVIEW, MONITORING, 👀 | review | | IN PROGRESS, IN_PROGRESS, 🔄 | in_progress | | PAUSED, ⏸️ | paused | | PLANNED, 📋 | planned | | Default | planned |

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:

| Evidence | Points | |----------|--------| | Commit message contains "fix/implement/complete/done" | +30 | | 3+ commits mentioning task | +20 | | Related beads issue is closed | +25 | | Related tests exist | +15 | | Activity within last 2 days | +10 |

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]

| Metric | Value | |--------|-------| | Confidence | 35/100 | | Last Activity | Today | | Commits | 2 |

Recent commits:

def456: "wip: TASK-YYY initial setup"

Stale Tasks (>7 Days)

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

| Task | Days Stale | Last Activity | |------|------------|---------------| | TASK-ZZZ | 14 days | 2026-01-11 |

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

| Location | Line | Status Found | |----------|------|--------------| | Table | 45 | 🔄 IN PROGRESS | | Header | 312 | (✅ DONE) |

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

Beads Mismatches

MASTER_PLAN.md and beads show different statuses.

| Task | MASTER_PLAN | Beads | Resolution | |------|-------------|-------|------------| | TASK-BBB | ✅ DONE | OPEN | bd close [id] | | TASK-CCC | 🔄 IN PROGRESS | CLOSED | Verify if done |

Orphan Task IDs

Found in git history but not in MASTER_PLAN.md.

| Task ID | Commit | Suggestion | |---------|--------|------------| | TASK-999 | abc123 | Add to MASTER_PLAN.md or archive |

Next Steps

Verify likely-done tasks with user, then run /done TASK-XXX
Fix inconsistencies by updating all 3 locations
Sync beads with bd close commands shown above
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.)

master-plan-auditor

Master Plan Auditor

Quick Start

Features

Workflow

Step 1: Parse MASTER_PLAN.md

Location Detection Patterns

Status Detection (Priority Order)

Step 2: Gather Evidence for IN_PROGRESS Tasks

Step 3: Calculate Confidence Scores

Step 4: Check Status Sync Across Locations

Step 5: Detect Stale Tasks

Step 6: Cross-Reference Beads

Step 7: Find Orphan Task IDs

Output Report Format

Still In Progress

TASK-YYY: [Title]

Stale Tasks (>7 Days)

Status Inconsistencies

TASK-AAA

Beads Mismatches

Orphan Task IDs

Next Steps