Skills
skills/michael-menard/monorepo/status-audit

status-audit

SKILL.md

/status-audit — Story Status Reconciliation

CRITICAL EXECUTION RULE: Do NOT spawn sub-agents (Task tool) for this skill. Call all MCP tools and Bash commands directly in the main conversation. Sub-agents do not have reliable access to the knowledge-base MCP server.

Usage

/status-audit [--fix] [--epic=platform] [--story=STORY-ID]

Examples:

/status-audit                          # Full audit of all platform stories (report only)
/status-audit --fix                    # Audit + apply all KB corrections
/status-audit --story=KBAR-0040        # Audit a single story
/status-audit --epic=platform --fix    # Audit + fix all platform stories

What It Does

Performs a five-part audit and optionally fixes all detected issues:

Section What It Checks
A. Legacy Stage Directories Stories that still exist in old-style stage dirs (backlog/, in-progress/, etc.) — flags for migration to flat stories/ layout
B. KB State Mismatch Stories in flat stories/ on disk vs KB state field — flags stories on disk not in KB, and vice versa
C. Orphaned Worktrees Active git worktree list entries vs worktree_list_active KB records
D. Deferred KB Writes DEFERRED-KB-WRITES.yaml files on disk that were never processed
E. Artifact Sync Key artifacts on disk (CHECKPOINT.yaml, EVIDENCE.yaml, QA-VERIFY.yaml) vs KB artifact records

Source of truth: The KB is the authoritative source for story state. Filesystem directories are for artifact storage only — status is never inferred from directory location.

Execution Steps

Step 0 — Parse Arguments

Extract --fix flag, --epic (default: platform), --story (optional single story filter).

Step 1 — Git Worktree Scan

Run via Bash tool:

git worktree list

Parse output into a map: { path → branch }. Extract story IDs from branch names matching pattern story/STORY-ID or story/STORY-ID-*.

Example:

/repo/tree/story/KBAR-0050  e2d613a4 [story/KBAR-0050]   → KBAR-0050
/repo/tree/story/WINT-1120  56f9fede [story/WINT-1120]    → WINT-1120

Store as GIT_WORKTREES: { storyId → { path, branch, commit } }

Step 2 — KB Worktree Query

Call MCP tool directly:

mcp__knowledge-base__worktree_list_active({})
→ KB_WORKTREES: { storyId → { path, branch, status } }

If tool fails, set KB_WORKTREES = {} and note in output.

Step 3 — Filesystem Scan

Scan A: Flat stories/ directories (canonical)

Run via Bash tool to find all story directories in the flat layout:

find plans/future/platform -type d \
  -regextype posix-extended \
  -regex '.*/stories/[A-Z]+-[0-9]+$'

For each path found, extract:

  • story_id: last path segment (e.g., KBAR-0040)
  • story_path: full path (e.g., plans/future/platform/wint/stories/KBAR-0040)

Store as DISK_STORIES: { storyId → { story_path } }

Scan B: Legacy stage directories (flag for migration)

Run via Bash tool to find stories still in old-style stage directories:

find plans/future/platform -mindepth 2 -maxdepth 5 -type d \
  -regextype posix-extended \
  -regex '.*/(backlog|created|elaboration|ready-to-work|in-progress|needs-code-review|failed-code-review|ready-for-qa|failed-qa|UAT|completed)/[A-Z]+-[0-9]+$'

For each path found, extract:

  • story_id: last path segment
  • stage_dir: parent directory name
  • legacy_path: full path

Store as LEGACY_STORIES: { storyId → { legacy_path, stage_dir } }. These are flagged in Section A.

If --story flag is set, filter both scans to just that story ID.

Step 4 — KB Story Query

Call MCP tool directly:

mcp__knowledge-base__kb_list_stories({
  epic: "platform",
  limit: 100
})

If result has 100 stories (may be paginated), call again with offset: 100, repeat until exhausted.

Store as KB_STORIES: { storyId → { state, story_dir, priority, blocked } }

Step 5 — Deferred KB Writes Scan

Run via Bash tool:

find plans/future/platform -name "DEFERRED-KB-WRITES.yaml" -type f

For each file found, read the first few lines to extract:

  • deferred_at timestamp
  • reason
  • story_id from the writes array

Store as DEFERRED_WRITES: [ { file_path, story_id, deferred_at, reason } ]

Step 6 — Artifact Scan

For each story in DISK_STORIES, check for key artifact files in the canonical path and its _implementation/ subdirectory:

# For each canonical_path:
ls {canonical_path}/
ls {canonical_path}/_implementation/ 2>/dev/null

Key artifacts to flag if present on disk:

  • CHECKPOINT.yaml or _implementation/CHECKPOINT.yaml
  • EVIDENCE.yaml or _implementation/EVIDENCE.yaml
  • QA-VERIFY.yaml or _implementation/QA-VERIFY.yaml
  • DEFERRED-KB-WRITES.yaml (already in Step 5, skip here)

Then check KB artifacts:

mcp__knowledge-base__kb_list_artifacts({ story_id: STORY_ID })

Only call kb_list_artifacts for stories that have at least one key artifact on disk and are in DISK_STORIES. Batch these calls — do not call for every story.

Compare disk artifacts vs KB artifact artifact_type values:

  • CHECKPOINT.yaml → type checkpoint
  • EVIDENCE.yaml → type evidence
  • QA-VERIFY.yaml → type qa_gate

Flag stories where disk artifacts exist but no corresponding KB artifact type is found.

Step 7 — Build Report

Section A: Legacy Stage Directories

For each story in LEGACY_STORIES:

STORY-ID  legacy: in-progress/STORY-ID  → needs migration to stories/STORY-ID/

Stories in legacy directories should be manually moved to {FEATURE_DIR}/stories/{STORY_ID}/ and the KB updated accordingly. Run with --fix to update KB state from these directories.

Section B: KB State Mismatches

Compare DISK_STORIES vs KB_STORIES:

  • If story is in DISK_STORIES but NOT in KB_STORIES: flag as Not in KB (on disk, not registered)
  • If story is in KB_STORIES but NOT in DISK_STORIES: flag as No directory (in KB, no story directory)
  • If KB_STORIES[id].story_dir doesn't match the path in DISK_STORIES: flag as Path mismatch

Also include stories from LEGACY_STORIES in KB comparisons — their KB state is preserved but directory needs migration.

Also flag if KB_STORIES[id].story_dir doesn't match the canonical path on disk.

Section C: Orphaned Worktrees

Cross-reference GIT_WORKTREES vs KB_WORKTREES:

  • In git but not in KB → Untracked worktree (git has it, KB doesn't know)
  • In KB but not in git → Orphaned KB record (KB thinks it's active, git worktree is gone)
  • In both → OK (show as healthy)

Section D: Deferred KB Writes

List all DEFERRED-KB-WRITES.yaml files with their age (current date minus deferred_at) and story ID.

Section E: Artifact Sync Gaps

List stories where disk artifacts exist but KB has no corresponding artifact record.

Step 8 — Output Format

═══════════════════════════════════════════════════════
STATUS AUDIT — plans/future/platform
Scanned: {N} stories on disk  |  {M} in KB  |  {date}
═══════════════════════════════════════════════════════

── A. LEGACY STAGE DIRECTORIES ({count} stories) ─────────────────────

  KBAR-0040  legacy: in-progress/KBAR-0040   → migrate to stories/KBAR-0040/
  LNGG-0030  legacy: UAT/LNGG-0030           → migrate to stories/LNGG-0030/
  ...

── B. KB STATE MISMATCHES ({count} stories) ─────────────────────────

  Story       Disk Dir        Disk State    KB State       Action
  ──────────  ──────────────  ────────────  ─────────────  ──────────────
  INFR-0040   UAT/            in_qa         ready_for_qa   UPDATE NEEDED
  KBAR-0020   UAT/            in_qa         ready          UPDATE NEEDED
  LNGG-0040   UAT/            in_qa         (not in KB)    INSERT NEEDED
  WINT-0110   UAT/            in_qa         ready          UPDATE NEEDED
  ...

── C. WORKTREES ({git_count} in git, {kb_count} in KB) ──────────────

  Story       Git Worktree                    KB Record   Status
  ──────────  ──────────────────────────────  ──────────  ───────────────
  KBAR-0050   tree/story/KBAR-0050            ✗ missing   UNTRACKED
  WINT-1120   tree/story/WINT-1120            ✗ missing   UNTRACKED
  WKFL-007    tree/story/WKFL-007             ✗ missing   UNTRACKED
  ...

── D. DEFERRED KB WRITES ({count} files) ────────────────────────────

  File                                              Story      Age     Reason
  ────────────────────────────────────────────────  ─────────  ──────  ──────────────────────────
  UAT/INFR-0040/DEFERRED-KB-WRITES.yaml            INFR-0040  10 days KB tools unavailable in PM
  ...

── E. ARTIFACT SYNC GAPS ({count} stories) ──────────────────────────

  Story       Disk Artifacts                    KB Artifacts   Missing in KB
  ──────────  ────────────────────────────────  ─────────────  ─────────────────
  INFR-0041   CHECKPOINT, EVIDENCE, QA-VERIFY   (none)         checkpoint, evidence, qa_gate
  AUDT-0010   CHECKPOINT, EVIDENCE              checkpoint     evidence
  ...

═══════════════════════════════════════════════════════
SUMMARY
  Legacy stage dirs:   {A_count} stories need migration
  KB state mismatches: {B_count} (updates needed)
  Orphaned worktrees:  {C_count}
  Deferred writes:     {D_count} files
  Artifact gaps:       {E_count} stories

{if --fix}
Applying fixes...
{else}
Run with --fix to apply all KB corrections.
{/if}
═══════════════════════════════════════════════════════

Step 9 — Apply Fixes (only if --fix flag is set)

Apply in this order:

Fix A: Legacy Stage Directories

Legacy stage directories cannot be auto-migrated (requires moving files and potentially active work). Flag as:

⚠ LEGACY directories require manual migration:
  For each story: mv {legacy_path} {FEATURE_DIR}/stories/{STORY_ID}/
  Then update KB story_dir:
    kb_update_story({ story_id, story_dir: "{FEATURE_DIR}/stories/{STORY_ID}" })

List each legacy path for easy access.

Fix B: KB State + story_dir Updates

For each mismatch in Section B:

mcp__knowledge-base__kb_update_story({
  story_id: STORY_ID,
  state: kb_expected_state,
  story_dir: canonical_path
})

For stories not in KB (INSERT NEEDED): use kb_get_story first to confirm absence, then use the appropriate insert tool. If no insert tool is available, flag for manual action.

Fix C: Worktree Records

For UNTRACKED (in git, not in KB): these are legitimate active worktrees — do NOT auto-register since we don't know if they're truly in-progress or abandoned. Instead, flag them with instructions:

⚠ UNTRACKED worktrees require manual verification:
  Run /wt-status to see full worktree health, then
  use /wt-finish or /wt-cleanup to resolve.

For ORPHANED KB records (in KB but not in git): call mcp__knowledge-base__worktree_mark_complete for each.

Fix D: Deferred Writes

These cannot be auto-applied here because the write payloads vary. Instead, output:

⚠ DEFERRED-KB-WRITES.yaml files must be processed manually:
  Run /kb-compress or read each file and apply writes via kb_update_story.

List each file path for easy access.

Fix E: Artifact Sync

Artifact content sync is out of scope for auto-fix (requires reading and re-uploading full file content). Flag as:

⚠ Artifact gaps noted. To sync, run /qa-verify-story or /checkpoint for each affected story,
  which will re-write artifacts to KB as part of normal workflow.

Step 10 — Post-Fix Summary

After applying fixes, show:

Fix Results:
  ✓ {N} KB story_dir paths corrected
  ✓ {N} orphaned worktree KB records marked complete
  ⚠ {N} legacy stage directories need manual migration
  ⚠ {N} untracked worktrees need manual review (/wt-status)
  ⚠ {N} deferred write files need manual processing
  ⚠ {N} artifact gaps need re-verification

Edge Cases

Scenario Behavior
Legacy story in UAT/ or other stage dir Flagged in Section A as needing migration to stories/ layout
Nested story dir (e.g., stories/KBAR-0020/KBAR-0020) Skip inner dir — it's an artifact folder
Story in git worktree but no active work / clearly abandoned Flag for manual review, don't auto-remove
kb_list_stories pagination Keep calling with increasing offset until total exhausted
Story on disk but --story filter doesn't match Skip
KB state is completed but story is in a legacy stage dir KB wins — KB is the authoritative source. Flag dir for migration.
Weekly Installs
15
Repository
michael-menard/monorepo
First Seen
14 days ago
Security Audits
Gen Agent Trust HubPass
SocketFail
SnykPass
Installed on
gemini-cli15
opencode15
codebuddy15
github-copilot15
codex15
kimi-cli15