Imported from mikeprasad/aria-knowledge (plugin-openai-codex/skills/audit-knowledge/SKILL.md). Install upstream with npx skills add mikeprasad/aria-knowledge --skill audit-knowledge. Copyright stays with the author.

/audit-knowledge — Knowledge Repository Audit

Scan ~/.claude/ memory and plan files, compare against what's already in the knowledge folder and project-level docs, and surface anything worth extracting.

Step 0: Resolve Config

Read ~/.claude/aria-knowledge.local.md and extract:

• knowledge_folder — required base path
• audit_cadence_knowledge — cadence in days (default 7); safety-net trigger for low-activity periods
• audit_trigger_threshold — backlog-entry count (default 20); primary activity-driven trigger. Tier boundaries derived via fixed offsets: threshold (suggested), threshold + 15 (recommended), threshold + 30 (overdue)
• projects_enabled — default false; controls whether project tier is audited (Step 5e)
• projects_list — default empty; comma-separated tag:path pairs; only relevant if projects_enabled: true
• projects_promotion_threshold — default 2; minimum projects sharing a similar pattern before Step 5e suggests cross-project promotion

If the config file doesn't exist, stop: "aria-knowledge is not configured. Run /setup to get started."

Use {knowledge_folder} as the base path for all file operations in subsequent steps.

Step 1: Read the Audit Log and Determine Mode

Read {knowledge_folder}/logs/knowledge-audit-log.md.

Note the "Last Audit" date and calculate days since.

Compute the current trigger state by counting ^### entries across the four action-eligible backlogs (insights, decisions, extraction, rules — exclude intake/ideas/, which routes out via the Accept submenu rather than promoting directly). Count only entries below the first --- separator per file, matching the convention used by /stats and /backlog:

for f in {knowledge_folder}/intake/insights-backlog.md \
         {knowledge_folder}/intake/decisions-backlog.md \
         {knowledge_folder}/intake/extraction-backlog.md \
         {knowledge_folder}/intake/rules-backlog.md; do
  [ -f "$f" ] && awk '/^---$/{sep++; next} sep>=1 && /^### /{c++} END{print c+0}' "$f"
done | awk '{s+=$1} END{print s+0}'

Record the count — it feeds both the prompt message and Step 8's Trigger: audit-log subfield.

Determine how this skill was invoked:

• User-requested (user said /audit-knowledge, "audit knowledge", "scan memory", etc.): Always run the full audit, regardless of how recently the last audit was. Skip directly to Step 2.
• Session-start check (triggered by the SessionStart hook): Check whether either trigger fired.
  • Entry-count trigger (primary): if backlog_count >= audit_trigger_threshold, prompt per tier:
    • count ≥ threshold + 30 → "Knowledge audit overdue — N entries, plan for multi-pass. Run /audit-knowledge?"
    • count ≥ threshold + 15 → "Knowledge audit recommended — N entries, near one-pass ceiling. Run /audit-knowledge?"
    • count ≥ threshold → "Knowledge audit suggested — N entries ready for review. Run /audit-knowledge?"
  • Elapsed-days trigger (safety net): if no entry-count tier fired AND days_since >= audit_cadence_knowledge, prompt: "Knowledge audit due — N days since last audit. Run /audit-knowledge?"
  • Neither fired: report the last audit date + current backlog count + days-since, then stop. "Last knowledge audit was N day(s) ago (YYYY-MM-DD). Backlog at M entries (threshold T). Next trigger at M=T entries or N=C days."

Step 1b: Check Index Freshness

Read {knowledge_folder}/index.md if it exists.

Several audit steps depend on index data (Step 5b entity refs + skill-knowledge drift, Step 5c tag matching, Step 6 stale files). Running against a stale or missing index produces incomplete results.

Check:

1. If index.md doesn't exist → note: "No index found. Steps 5b (entity/skill checks), 5c (tag matching), and stale file detection will be limited. Consider running /index after this audit."
2. If index.md exists → read the Last rebuilt: date from the header. Compare against today.
   • If older than 7 days AND there are pending backlog entries (from a quick line count of the 3 backlog files) → prompt: "Index was last rebuilt N days ago and there are pending backlog items. Run /index first for more accurate integrity checks? (y/n)"
   • If user says yes → run the full /index logic (Steps 0-10 from the /index skill), then continue with Step 2
   • If user says no → continue with degraded checks (note in Step 6 output which checks were limited)
   • If 7 days or fewer → continue normally, index is fresh enough

This is a lightweight check — it reads one file header and counts backlog lines. The expensive work (full index rebuild) only happens if the user opts in.

Step 2: Review Insights Backlog

Read {knowledge_folder}/intake/insights-backlog.md. If the file is missing, report it in Step 6 and suggest running /setup to repair the structure. Do not create it.

If there are entries below the --- separator, these are insights captured during work sessions that need review.

For each insight entry, note it for presentation in Step 6 alongside Category C items. Insights are reviewed with the same approve/reject flow — promoted ones go to the appropriate knowledge file, rejected ones get cleared from the backlog.

Step 2b: Review Decisions Backlog

Read {knowledge_folder}/intake/decisions-backlog.md. If the file is missing, report it in Step 6 and suggest running /setup to repair the structure. Do not create it.

If there are entries below the --- separator, these are cross-project architectural decisions captured during work sessions that need review.

For each decision entry, note it for presentation in Step 6. Decisions are reviewed with the same approve/reject flow — promoted ones become full ADRs in {knowledge_folder}/decisions/ (using ADR format), rejected ones get cleared from the backlog.

Step 2c: Review Extraction Backlog

Read {knowledge_folder}/intake/extraction-backlog.md. If the file is missing, report it in Step 6 and suggest running /setup to repair the structure. Do not create it.

If there are entries below the --- separator, these are feedback, project context, and reference items captured via /extract during work sessions.

For each entry, note it for presentation in Step 6. Feedback items are promoted to ~/.claude/projects/ memory as feedback memories. Project context items become project memories. Reference items become reference memories or go to {knowledge_folder}/references/. Rejected items get cleared from the backlog.

Reclassification check: If any entry reads as a feature proposal, bug report, or design idea (rather than an observation about what IS), flag it for re-routing to intake/ideas/ (as a new per-file idea) during Step 7. Common signals: "should", "could be better if", "missing handling for", "UX gap", "would help if". Misclassified proposals will otherwise get promoted into knowledge files where they sit as documentation of things that don't exist — a known drift mode.

Step 2c2: Review Ideas Directory

Glob {knowledge_folder}/intake/ideas/*.md. If the directory is missing, report it in Step 6 and suggest running /setup to repair the structure. Do not create it.

Counting note: When reporting an idea count (Step 6's Pending Ideas (N) header and Step 8's Plus N ideas audit-log subfield), filter out README.md and .gitkeep from the glob result — they're directory-purpose files, not ideas, and inflate counts by 1-2 if included. The reads-and-categorize step below is unaffected since non-idea files lack the required date:/project:/type:/title: frontmatter and are skipped during per-file review. Concrete primitive: ls intake/ideas/*.md 2>/dev/null | grep -v 'README\|\.gitkeep' | wc -l.

Legacy-file detection (one-time): Also check for {knowledge_folder}/intake/ideas-backlog.md. If it exists alongside intake/ideas/, surface a finding in Step 6 under a "Legacy Ideas Backlog" note: "Pre-2.11 ideas-backlog.md detected. Run bash ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/bin/migrate-ideas-backlog.sh {knowledge_folder} or re-run /setup to migrate entries into per-file format." Do not attempt the migration from within the audit flow.

For each *.md file in intake/ideas/: read the file (frontmatter + body). Each file is one idea — feature proposal, bug report, or design idea captured via /extract. Ideas have a distinct disposition from other backlogs — they do NOT promote to knowledge files directly. Present them in their own section in Step 6 with the options:

• Accept — pick a destination from the submenu below. After the user approves, run the verify-no-loss check (below). Idea file then moves either to its destination (full-body preservation) or to {knowledge_folder}/archive/audit-{date}/ (summary-only destinations — body preserved in archive with demoted-to: {destination} frontmatter)
• Reject — idea file moves to {knowledge_folder}/archive/audit-{date}/ with dismissal-reason: {one-line} frontmatter
• Defer — file stays in place for the next audit cycle (no-op)
• Reclassify — if on review the item is actually an observation, append its content to the appropriate knowledge backlog (insights/decisions/extraction) for normal promotion, then move the idea file to {knowledge_folder}/archive/audit-{date}/ with reclassified-to: {backlog#section} frontmatter

Never delete (v2.15.1+): Idea files are NEVER rm'd. Every disposition that previously deleted now moves the file — to its destination (full-body preservation) or to archive/audit-{date}/ (with a frontmatter pointer explaining why). Rule 6 ("Don't delete — archive") is preserved without relying on git history; archive-on-disk is the canonical surface, making non-git knowledge folders first-class.

User override (explicit, v2.15.2+): If the user explicitly approves or asks for a deletion (phrases like "delete without archiving", "really delete this", "skip the archive for this one"), the destructive operation is permitted. The default safety floor remains archive; the override exists for cases where the user has explicit reason to skip preservation (e.g., accidentally captured sensitive content, archive-growth aversion). Before honoring an override, surface what would have been archived — name the file(s) and the substance about to be lost — and confirm. User-approved deletes are then honored as one-off; the override does not flip the default for subsequent files in the same audit.

Verify-no-loss check (Accept disposition)

Before the idea file moves to its Accept destination, verify the destination preserves the idea's substantive content. This protects against the silent-summarization-then-delete failure mode (where a destination's 1-line entry replaces a multi-paragraph body).

1. Inventory original substance: identify which of {Why, Motivation, Implementation sketches, Source} sections exist in the idea file (frontmatter + body).
2. Inventory destination coverage: read the planned destination entry — does it carry text covering each substantive section present in the source?
3. Three outcomes per idea:
   • Full coverage → idea file mv's to the destination as a standalone file (new ADR / approach / reference / plan / project decisions/patterns/), OR is fully expanded as a multi-paragraph entry in the destination (backlog/roadmap entries that carry the full Why/Motivation/Implementation paragraphs, not just a 1-liner). Original idea file gone from intake/ideas/; substance lives at destination.
   • Insufficient coverage (typical for summary-style destinations: 1-line ROADMAP bullets, TODO entries, tracker summaries) → idea file mv's to archive/audit-{date}/{filename} with demoted-to: {destination#section} frontmatter. The destination still receives its summary entry; the archive preserves the body.
   • Partial coverage → surface to user: "Substantive sections X, Y from the original would be missing at {destination}. Choose: (a) expand destination to include them, (b) archive original alongside, (c) accept the compression as a knowing demotion." Default recommendation: (b) for backlog-style destinations, (a) for promotion-style destinations.

Edits/revisions during move are expected and welcome — the rule is no useful substantive content is lost, not body is byte-identical to source. Reformatting, condensing redundant phrasing, fixing grammar, recontextualizing for the destination format are all fine. The verification gate catches loss, not change.

Accept submenu — destinations:

Project-root detection: for roadmap, todo, and backlog paths, the audit needs to resolve the idea's project tag to a filesystem path before probing for files. Resolution rules (in priority order):

1. Tag in projects_list — if projects_enabled: true AND the idea's project tag matches a tag:path pair in projects_list, resolve to that path. Paths in projects_list are relative to the parent directory of the knowledge folder (typically ~/Projects/); the audit converts to absolute by prepending that parent.
2. CWD fallback — if the tag isn't resolvable via projects_list (projects tier disabled, tag missing from list, or idea's project is cross / no-project), fall back to the current working directory. Probe the closest ancestor of CWD containing either .git/ or CLAUDE.md.
3. No resolution possible — if neither path strategy yields a valid directory (e.g., projects tier disabled AND CWD has no git/CLAUDE.md ancestor), omit roadmap, todo, and backlog from the submenu and append a one-line note to that idea's audit entry: "roadmap/todo/backlog not offered: project path unresolved (project tag not in projects_list, no .git/ or CLAUDE.md ancestor of CWD)." This makes the gap visible rather than silently shrinking the submenu.

Once the project root is resolved, probe for the relevant file in two locations in this order: (1) project root, (2) docs/ subdirectory of the project root. Tie-break when both exist: route to the project root copy; the docs/ copy is treated as secondary and not modified. Document the chosen path in the audit log entry so users can trace where each idea landed.

Ticketing plugin lookup: read ticketing_plugins from ~/.claude/aria-knowledge.local.md (format: comma-separated tag:plugin-command pairs, e.g., proj-a:foo-ticket,proj-b:bar-ticket). If the idea's project matches a mapped tag, append a hint line under the tracker option: "Use /{plugin-command} to draft this as a ticket." Never invoke the other plugin's skill from inside this audit — the hint is informational; the user invokes manually.

No installed-plugin probe. The audit does not verify that {plugin-command} is actually installed on the user's system before printing the hint. This is intentional: enumerating installed plugins from inside a skill couples ARIA to Claude Code internals that could change. If the user has ticketing_plugins: cs:foo-ticket set but /foo-ticket is uninstalled, the hint still prints; the user discovers via "command not found" on invocation. Loud-fail at invocation is preferred over a silent absent hint.

Bundle clustering — auto-detected at audit time. Group pending idea files where:

1. project frontmatter matches across 2+ files, AND
2. Titles share ≥2 significant words after tokenization (see below).

Tokenization rules (applied to the title: frontmatter field — fall back to the slug portion of the filename if title: is missing):

• Split on whitespace AND on hyphens (kebab-case + spaces both produce tokens).
• Lowercase all tokens.
• Strip leading/trailing ASCII punctuation from each token.
• A token is significant if its length ≥ 3 chars AND it is not in the stop-words list: a, an, and, the, to, for, of, in, on, with, from, by, is, be, or, but, not, no, do, did, has, had, will, can.
• Word match is exact (case-insensitive after normalization). No stemming, no fuzzy matching — keeps clustering deterministic across audit runs.

Lead entry of a cluster: the oldest idea by the date: frontmatter field; if date: is missing or malformed, fall back to the YYYY-MM-DD filename prefix. Tie-break: alphabetical by full filename. The lead entry is where the audit surfaces the bundle option in Step 6; the other cluster members reference back to the lead.

For each detected cluster, surface a bundle option once in the cluster's lead entry in Step 6 (with a list of cluster members). The user chooses bundle (then picks merged-file destination + writes a one-line cluster summary) OR disposes each idea individually.

Bundle sub-prompt destinations: when a bundle is accepted, the sub-prompt offers tracker | roadmap | todo | adr | backlog (the same conditional availability rules as a single idea's submenu). Excluded from bundle sub-prompts: bundle (would recurse) and rule (rule candidates are intentionally one-rule-per-entry — bundling rule candidates obscures their individual review under audit Step 2c3, which expects one rule per ### YYYY-MM-DD — {title} block).

The archive folder {knowledge_folder}/archive/audit-{date}/ is the canonical preservation surface for any idea file whose disposition was Reject, Reclassify, Bundle, or Accept-with-insufficient-coverage. Git tracking is no longer assumed — first-class support for non-git knowledge folders. Each archived file gains frontmatter (dismissal-reason, reclassified-to, bundled-into, or demoted-to) explaining why it was archived and where its substance lives (if anywhere). After all Step 2c2 dispositions resolve, write a per-audit {knowledge_folder}/archive/audit-{date}/MANIFEST.md capturing the cohort:

---
audit_date: YYYY-MM-DD
audit_pass: <pass number from audit log>
ideas_touched: N
moved_to_destination: N (full-body preservation; see per-idea audit log entries for destinations)
archived: N
  - dismissal (rejected): N
  - reclassified-to-backlog: N
  - bundled: N
  - demoted-to-summary-destination: N
---

Followed by a per-archived-file list with the originating idea filename + frontmatter pointer. The MANIFEST is the human-readable counterpart to the audit log; the audit log records dispositions, the MANIFEST records the archive's contents.

Prior versions (pre-v2.15.1) assumed git log --all -- intake/ideas/ would recover deleted bodies. That assumption silently failed for any idea file created since the last git commit (untracked file → working-tree delete → no history). v2.15.1 archives unconditionally; never delete is the new safety floor.

Ideas never promote to approaches/, decisions/, or rules/ directly via Accept — those land in their respective backlogs (adr → decisions-backlog.md, rule → rules-backlog.md) for normal audit-cycle review. The audit report for ideas presents the submenu inline; routing is a user action invoked by their disposition choice.

Age annotation and stale marker: For each idea file, compute age as (today - idea date) in days. Derive the idea date as follows: (1) read date: from YAML frontmatter; (2) if missing or malformed, fall back to the YYYY-MM-DD prefix of the filename. Annotate each entry with its age (filed N days ago). Read the staleness threshold from ~/.claude/aria-knowledge.local.md (ideas_staleness_threshold_days, default 7) via config.sh or fallback. When age > threshold, append a [STALE — still relevant?] marker to the entry and escalate its visual weight in Step 6 (place stale entries first within the Pending Ideas section, and prompt explicitly for Accept/Reject/Defer rather than allowing implicit Defer).

This is the audit's mechanism for forcing action on long-sitting ideas. Without staleness surfacing, items accumulate silently; with it, every audit cycle either confirms an idea still matters or retires it.

Step 2c3: Review Rules Backlog

Read {knowledge_folder}/intake/rules-backlog.md. If the file is missing, report it in Step 6 and suggest running /setup to repair the structure. Do not create it.

If there are entries below the --- separator, these are rule candidates — observations or proposals about how to work (rather than what is) — staged via the Accept → rule path on prior idea audits, or appended directly when feedback in conversation matches a "rule of thumb" shape.

For each entry, note it for presentation in Step 6 alongside other backlogs. Rule candidates have three valid promotion targets, all inside the user memory directory or {knowledge_folder} (ARIA never writes to project source):

• User memory feedback_*.md — for personal/working-style rules that span projects (matches the existing feedback-memory pattern under the active project's ~/.claude/projects/{cwd-encoded}/memory/ directory)
• Cross-project {knowledge_folder}/rules/user-rules.md — for ARIA-behavior rules that should apply consistently across all the user's work (the user-owned counterpart to plugin-managed working-rules.md)
• Project-tier {knowledge_folder}/projects/{tag}/rules/working-rules.md — only when projects_enabled: true and the entry's project tag matches projects_list; for project-scoped discipline that doesn't generalize cross-project. Setup's Step 7c scaffolds the parent rules/ subdirectory so this destination is always available when the projects tier is on.

Rejected entries get cleared from the backlog. All three promotion targets are reviewed at user approval time in Step 7 — do not auto-promote.

Reclassification check: if any entry reads as a feature proposal or bug report (rather than a "how to work" rule), flag it for re-routing to intake/ideas/ during Step 7. Common signals indicating misclassification: "should add", "should fix", "would be nice if X existed". Rules describe behavior; ideas describe missing features.

Step 2d: Review Pre-Compact Captures

Scan {knowledge_folder}/intake/pre-compact-captures/ for .md files. If the directory doesn't exist or is empty, skip silently to Step 3.

If snapshots exist, report the count and total size, then ask the user:

"Found N pre-compaction transcript snapshot(s) (total ~X KB) from previous sessions. These may contain uncaptured knowledge. Options:"

1. Digest — extract high-signal content via script, then review (~1-3K tokens per snapshot; default)
2. Detailed — read full transcripts for exhaustive review (~30-50K tokens per snapshot)
3. Skip — leave them for a future audit
4. Clear — ledger-clear all snapshots without reviewing (v2.15.2+: bodies removed but a REMOVED.md ledger records session-ids + timestamps + pointers to Claude Code's canonical transcript log)

• If Skip → skip to Step 3, leave files untouched
• If Clear → apply the ledger-clear pattern (v2.15.2+):
  1. Create {knowledge_folder}/archive/audit-{date}/pre-compact-captures/ if it doesn't exist
  2. Write {knowledge_folder}/archive/audit-{date}/pre-compact-captures/REMOVED.md with frontmatter (audit_date, removed_count, canonical_source: ~/.claude/projects/...) + a per-snapshot list of filename + session-id + capture-timestamp + canonical-jsonl-pointer. See the ledger schema at the end of this section.
  3. After the ledger is written, rm the snapshot .md files from intake/pre-compact-captures/. Bodies are derived copies of Claude Code's per-session transcript log — canonical preservation is at ~/.claude/projects/{cwd-encoded}/{session-id}.jsonl (until Claude Code rotates that log).
  4. Report count cleared, skip to Step 3.
• If Digest or Detailed → continue with the selected mode below

Digest mode (default): For each transcript snapshot, run the digest script to extract high-signal content before reading:

bash ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/bin/digest-transcript.sh "{snapshot_path}" "/tmp/aria-digest-{filename}"

Then read the digest file (not the raw transcript). The digest keeps all user messages (truncated at 500 chars), first/last 5 lines of each assistant turn, Insight blocks, and lines containing decision/feedback signal keywords. Tool calls and results are dropped entirely. Typical reduction: ~97% fewer tokens vs raw transcript (~1-3K tokens per snapshot vs ~30-50K+ raw).

Detailed mode: Read the full transcript snapshots directly. Use this when digest mode missed something in a previous audit or when the session contained complex multi-step work where mid-response context matters. Note: a single snapshot can consume 30-50K+ context tokens, so use sparingly.

For each snapshot (digest or full):

1. Note the filename (contains date and session ID, e.g., 2026-04-07_a1b2c3d4.md)
2. Scan for extractable content — look for the same categories as /extract: Insight blocks, architectural decisions, feedback corrections, project context, and reference pointers
3. Note findings for presentation in Step 6 under a "Pre-Compact Captures" section

4. Re-verify every finding against HEAD before presenting it as live (REQUIRED). A capture is a snapshot of a moment, not of current state — the session it records may have fixed the very thing it describes, minutes later. For any finding that asserts a present-tense defect ("X is unguarded", "the test asserts Y", "this window is open"), check the current source before it reaches Step 6: read the file at HEAD, and git log --oneline -5 -- <path> on the repo the finding names. Mark each as STILL LIVE (verified at HEAD) or ALREADY FIXED (closed by <sha>). Findings that fail this check are reported as historical, never filed and never promoted as current.

Basis (2026-08-01, 108th pass): two capture-derived findings — a test asserting the ambient environment, and a safety matrix hiding a forged-header window — were surfaced as live security hazards. Both had been closed the same day by a commit whose message named them exactly. Under a standing grant to file tickets without asking, acting on the digest would have filed two duplicate security tickets. This is the same obsolescence discipline Step 2c2 applies to ideas; captures had no equivalent gate.

After the user reviews findings in Step 7:

• Approved items → append to the appropriate backlog file (insights-backlog.md, decisions-backlog.md, or extraction-backlog.md), then apply the ledger-clear pattern (see below) to the snapshot file — body removed, REMOVED.md ledger entry appended.
• Rejected items → apply the ledger-clear pattern to the snapshot file — body removed, REMOVED.md ledger entry appended with disposition: rejected and a one-line reason from the user.
• Skip → leave the snapshot for the next audit

Ledger schema (v2.15.2+)

Pre-compact snapshots are derived copies of Claude Code's per-session transcript log at ~/.claude/projects/{cwd-encoded}/{session-id}.jsonl. Their bodies are not preserved in the archive — only a ledger of what existed is preserved. The body's canonical source is the Claude Code transcript log (until Claude Code rotates it).

Ledger file: {knowledge_folder}/archive/audit-{date}/pre-compact-captures/REMOVED.md

---
audit_date: YYYY-MM-DD
removed_count: <N>
canonical_source_pattern: ~/.claude/projects/{cwd-encoded}/{session-id}.jsonl
note: |
  Pre-compact snapshots are derived copies of Claude Code's per-session transcript log.
  Bodies are not archived here; the canonical source retains them until Claude Code rotates
  the jsonl. If a snapshot needs recovery after rotation, the body is unrecoverable.
---

# Removed pre-compact snapshots — {audit-date} audit

- {filename} | session {session-id} | captured {capture-iso8601} | disposition: clear|approved|rejected | reason: {one-line} | canonical: ~/.claude/projects/.../{session-id}.jsonl
- ...

Append-only — if a subsequent audit on the same date also ledgers snapshots, append rows under the same REMOVED.md. If a same-date audit folder already exists from a prior run, suffix as audit-{date}-2/, -3/, etc.

User override (explicit, v2.15.2+): If the user explicitly approves or asks for a snapshot deletion that skips even the ledger (phrases like "delete the snapshots without writing a ledger", "just rm them"), the bare deletion is permitted. The default remains ledger-clear; this override exists for cases where the user has explicit reason to skip both archive AND ledger (e.g., snapshots contain sensitive content they want untraceable). Before honoring, surface the snapshot count + canonical-source pointers that would have been ledgered and confirm. User-approved bare deletes are one-off; subsequent snapshot operations in the same audit default back to ledger-clear.

Step 2e: Review Subagent Captures

Scan {knowledge_folder}/intake/subagent-captures/ for .md files. If the directory doesn't exist or is empty, skip silently to Step 3.

If captures exist, report the count and total size, then ask the user:

"Found N subagent transcript capture(s) (total ~X KB) archived from heavyweight subagents. A subagent cannot extract its own session, so these are held until reviewed. Options:"

1. Digest — extract high-signal content via script, then review (~1-3K tokens per capture; default)
2. Detailed — read full transcripts for exhaustive review (~30-50K tokens per capture)
3. Skip — leave for the next audit

There is no bare-Clear option for subagent captures. Unlike pre-compact snapshots (derived copies of Claude Code's canonical session .jsonl), a subagent capture is held under sticky retention — its body is only removed after its knowledge is folded into a backlog, because the subagent's source transcript is not assumed to persist.

Digest mode (default): for each capture, run:

bash ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/bin/digest-transcript.sh "{capture_path}" "/tmp/aria-digest-{filename}"

Then read the digest (not the raw transcript). Extract findings into the standard six buckets (insights, decisions, feedback, project context, references, ideas) — same categorization as /extract.

Detailed mode: read the full capture directly. Use sparingly (a single capture can consume 30-50K+ tokens).

Re-verify against HEAD before presenting any finding as live (REQUIRED) — the same gate as Step 2d item 4, and it bites harder here: adversarial /prospect and /retrospect subagents exist precisely to find defects, so their captures are dense with present-tense claims, and the parent session very often fixed them immediately. Mark each finding STILL LIVE (verified at HEAD) or ALREADY FIXED (closed by <sha>) before Step 6.

For each reviewed capture:

• Approved items → append to the appropriate backlog (insights-backlog.md, decisions-backlog.md, or extraction-backlog.md), then apply the ledger-clear pattern: create {knowledge_folder}/archive/audit-{date}/subagent-captures/ if needed, append an entry to its REMOVED.md (filename + parent-session-id + agent_type + agent_id + capture-timestamp), then rm the capture .md.
• Rejected items → ledger-clear with disposition: rejected and a one-line reason.
• Skip → leave the capture for the next audit.

Note findings for presentation in Step 6 under a "Subagent Captures" section.

Step 2f: Review Clippings

Scan {knowledge_folder}/intake/clippings/ for .md files and image files (.png, .jpg, .jpeg, .gif, .webp). If the directory doesn't exist or is empty, skip silently to Step 3.

If clippings exist, report the count and total size — broken out as markdown vs images (e.g., "N clipping(s): M markdown, K images") — then ask the user:

"Found N clipping(s) (total ~X KB) — saved URLs / snippets / threads (captured via /intake or dropped into the folder by hand), plus K image(s). Options:"

1. Graduate (default) — preserve each clipping whole as a durable source in references/sources/ AND mine it for knowledge
2. Skip — leave for the next audit

Image cost guard: if there are more than 5 images, warn that each is a non-trivial vision read and offer review all / review first N / defer the rest to next audit before processing. (≤5: process inline.)

Under Graduate, for each clipping:

1. Derive tags. Propose tags from the clipping's content, matched against the existing tag vocabulary in index.md (mirror /index's tagging). If the clipping already carries /intake frontmatter tags:, carry them over. Show the proposed tags for confirm/edit before writing.
2. Preserve the source. Ensure the clipping has Last updated: + the confirmed tags: frontmatter, then move the whole file to {knowledge_folder}/references/sources/{filename}.md (create references/sources/ if absent). Move rule: use git mv only when the specific file is git-tracked — check with git ls-files --error-unmatch "{path}"; if it's untracked (even inside a git repo), use plain mv (a bare git mv fails on untracked files and would silently leave the clipping behind). This applies to image assets too.
3. Mine all six buckets (insights, decisions, feedback, project context, references, ideas) — same scan as /extract. Append findings to the appropriate backlog (insights-backlog.md / decisions-backlog.md / extraction-backlog.md) and route ideas to intake/ideas/. Reference-type fragments become curated notes destined for top-level references/ (a distinct tier from the raw source now in references/sources/). Because the whole source is preserved in references/sources/, dedup any reference fragment against it before promoting — promote a fragment only when it is a distinct, smaller, independently-useful note, not a restatement of the source.
4. Ledger as graduated. Create {knowledge_folder}/archive/audit-{date}/clippings/ if needed; append an entry to its REMOVED.md: filename + source + clip-date + disposition: graduated + destination references/sources/{filename}.md.
5. No minable content: the source STILL graduates to references/sources/ (archival value). Ledger note disposition: graduated (source only, no fragments mined).

Image clippings (.png/.jpg/.jpeg/.gif/.webp) take an image sub-flow instead of the markdown mine path above:

1. Vision-read the image via the Read tool (model-native; no OCR/script dependency). If the image is unreadable/corrupt, skip it with a one-line note in the Step 6 report and leave it in clippings/ (don't graduate a file you couldn't open).
2. Transcribe the content to text — a faithful rendering of the visual (nodes + edges for a diagram, on-screen text for a screenshot, series/values for a chart), not just a caption. If content is ambiguous, transcribe what's legible and flag the uncertainty in the transcription body.
3. Derive + confirm tags (same as markdown step 1).
4. Tier decision (per image): ask whether the transcription is a faithful-twin of the image (→ write it to references/sources/{name}.md, beside the asset) or distilled knowledge that stands alone (→ write it to top-level references/{name}.md). Suggest a default — twin if it largely restates an existing synthesis, distilled if it stands alone — and let the user confirm.
5. Graduate the asset: move the image to references/sources/{filename} (see the tracked-file move rule in markdown step 2).
6. Mine the transcribed text into the six buckets exactly as a markdown source; dedup reference fragments against any existing synthesis (cross-link, never duplicate).
7. Ledger in archive/audit-{date}/clippings/REMOVED.md: {image} | disposition: graduated (image; transcribed → {transcription-path}) | dest: references/sources/{image}.
8. No minable content (decorative/illustrative): the asset still graduates; ledger graduated (image, source only); still write a minimal caption/transcription so the asset is findable.

There is no discard-the-source path: every processed clipping graduates. "Skip" defers an uncertain clipping to the next audit.

Note findings for presentation in Step 6 under a "Clippings" section (report each as graduated → references/sources/{filename} plus any mined items).

Step 3: Scan Memory Files

Read all .md files in ~/.claude/projects/ memory directories for the current project (excluding MEMORY.md itself).

Issue Read calls for all matching files in a single parallel tool-use block. A/B/C categorization runs in the main thread after all reads complete — do not categorize file-by-file serially.

If the directory does not exist or contains no .md files: report "No memory files found for the current project" in the Step 6 summary and skip to Step 4. Do not silently omit this section.

For each file, categorize:

• (A) Already captured — content is already in CLAUDE.md files, {knowledge_folder}/, or project docs
• (B) Claude-implementation-specific — operational details about Claude sessions, plans, or tooling that don't contain reusable knowledge
• (C) Worth extracting — contains validated approaches, non-obvious patterns, or cross-project knowledge not yet captured

Step 4: Scan Plan Files

Read all files in ~/.claude/plans/.

Issue Read calls for all plan files in a single parallel tool-use block. Categorization runs in the main thread after reads complete.

If the directory does not exist or contains no files: report "No plan files found" in the Step 6 summary and skip to Step 5. Do not silently omit this section.

Apply the same A/B/C categorization. Most plans are Category B (implementation-specific). Look specifically for:

• Validated approaches or patterns that could go in {knowledge_folder}/approaches/
• Cross-project decisions that could go in {knowledge_folder}/decisions/
• Rules or principles validated through experience that could go in {knowledge_folder}/rules/
• Operational knowledge (tool setup, architecture, onboarding) that could go in {knowledge_folder}/guides/

Step 5: Cross-Reference with Knowledge Repository

Read the existing knowledge files to avoid duplicates:

Expand the glob patterns first (via Glob), then issue Read calls for all resolved files in a single parallel tool-use block. These file contents feed Steps 5b (integrity lint) and 5c (cross-reference) — do not re-read in those steps.

{knowledge_folder}/README.md
{knowledge_folder}/rules/*.md
{knowledge_folder}/approaches/*.md
{knowledge_folder}/decisions/*.md
{knowledge_folder}/guides/**/*.md
{knowledge_folder}/references/*.md

Also check project-level CLAUDE.md and docs files in the current working directory for already-captured knowledge.

Step 5b: Lint Knowledge Integrity

Using the knowledge files already read in Step 5 (do not re-read), scan for internal problems across the existing knowledge base. This is not about what's missing — it's about what's broken or disconnected in what we already have.

Check for:

• Contradictions — rules, approaches, or decisions that conflict with each other (e.g., a rule says "always X" but an approach says "avoid X in this context" without acknowledging the rule)
• Stale references — file paths, rule numbers, tool names, or class names mentioned in knowledge files that no longer exist in the codebase or knowledge repo. Verify by checking the filesystem — don't rely on memory.
• Superseded content — decisions in decisions/ or the decisions backlog that modify or override an existing approach or rule, but the approach/rule hasn't been updated to reflect this
• Missing connections — files that discuss the same concepts, patterns, or components but don't reference each other (e.g., an approach that implements a rule but doesn't cite it, or two decisions about the same system with no cross-link)
• Stale entity references — if index.md has an ## Entities section, check that listed files still exist and still mention the entity. Flag any entries pointing to archived, renamed, or deleted files.
• Missing entities — scan promoted files for named tools, services, or frameworks that appear in 2+ files but are not listed in the entity index. These should be picked up by the next /index run, but flagging them during audit ensures awareness.
• Skill-knowledge drift — if index.md has a ## Skill Connections section, check each connection for staleness. For each row in the table: (1) Get the skill file's modification date via stat or ls -l on ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/{skill_name}/SKILL.md. (2) Get the knowledge file's Last updated date from its YAML frontmatter. (3) If the skill file is newer than the knowledge file, flag as potential drift — the skill may have evolved past what the knowledge doc describes. Also scan the knowledge file content for terms that may be stale relative to the skill (e.g., old names, deprecated patterns). If no ## Skill Connections section exists in the index, skip this check silently — it means /index hasn't been run with Step 8c yet.

Scope: Only check files in {knowledge_folder}/rules/, {knowledge_folder}/approaches/, {knowledge_folder}/decisions/, {knowledge_folder}/guides/, and {knowledge_folder}/references/. Do not lint backlogs, logs, or templates.

Threshold: Only flag issues where the inconsistency is clear and actionable. "This rule could be interpreted as conflicting" is not a finding. "Rule 14 says max 3 abstraction layers; approach X recommends 5 without addressing why" IS a finding.

Note all findings for presentation in Step 6 under the new "Integrity Issues" section.

Step 5b3: Check Cross-Skill Shared-Block Drift

Some skills inline shared logic (e.g., the group-loader block shared between /distill and /stitch). Drift between inlined copies is a latent bug — users would see different behavior in each skill.

1. Grep all files under ${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/**/SKILL.md for <!-- shared-block: NAME --> markers.
2. For each unique block NAME, collect the content between <!-- shared-block: NAME --> and <!-- /shared-block: NAME --> in every skill that contains it.
3. Normalize whitespace (collapse multiple spaces and blank lines to single).
4. If collected contents differ across skills for the same block name, flag as drift.

Note findings for presentation in Step 6 under a "Shared-Block Drift" section.

Do not auto-fix drift — only surface the finding. The resolution is a deliberate choice: update one skill to match the other, or intentionally diverge (in which case rename the block in one skill — e.g., group-loader-distill — so it no longer shares the name with the other).

Step 5c: Cross-Reference Backlog Against Promoted Docs

For each pending backlog entry (from Steps 2, 2b, 2c), check whether it overlaps with existing promoted knowledge files.

How to match:

1. If {knowledge_folder}/index.md exists, read it and use the tag index for matching. Extract keywords from the backlog entry and check if any match tags in the index.
2. If no index exists, fall back to keyword matching: scan headings and first paragraphs of files in approaches/, decisions/, guides/, references/ for overlapping terms.

Two types of overlap to detect:

Topic overlap — the backlog entry covers a topic that already has a promoted doc:

• A backlog insight about pagination when approaches/api-pagination.md exists
• Flag: "This insight may relate to existing doc approaches/api-pagination.md — update existing rather than create new?"

Potential invalidation — the backlog entry describes a change that may affect existing promoted docs:

• A clipping about a new Stripe API version when references/stripe-webhook-patterns.md exists
• A decision that reverses or modifies an existing approach
• Flag: "New entry about [topic] — existing [file] may need review or update."

Note all cross-references for presentation in Step 6. These inform the user's promotion decisions — they're not blockers.

Step 5d: Check Codemap Staleness

Scan the current working directory for CODEMAP.md files:

Glob for **/CODEMAP.md in the project root

For each CODEMAP.md found:

1. Read the header only (first ~10 lines) to extract the Last updated: date
2. Calculate age in days since last update
3. Check for codebase changes — run git log --name-only --since="{last_updated}" --pretty=format:"" -- {project_path} to count files changed since the codemap was last updated
4. Read the Build Log (last ~30 lines) to check per-section update dates

Staleness criteria:

• Stale if more than 30 days since last update AND the codebase has changed files in that period
• Possibly stale if more than 14 days and >20 files changed
• Current otherwise

Note findings for presentation in Step 6 under a "Codemap Staleness" section.

Do not run /codemap update automatically — it consumes significant tokens. Only present the finding and let the user decide.

Step 5d2: Check Codemap Stack-Concern Coverage

For each CODEMAP.md found in Step 5d, verify stack-level cross-cutting concerns are captured. Feature-organized codemaps systematically under-document cross-cutting framework layers (signals, migrations, URLConfs, env matrices) because those don't attach to any single feature.

1. Detect the stack from the codemap (grep the first ~50 lines for Django, Next.js, Laravel, Expo, or the Stack: header).
2. Grep the full codemap for expected stack-concern keywords:
   • Django: URLConf tree, Signal registry|post_save|pre_save, Migration state|latest migration, Env matrix|env var table
   • Next.js / React: Route tree|Route overview, API client|interceptor, Env matrix
   • Laravel: Route file|routes/web.php, Job registry|queue, Service provider, Env matrix
   • Expo / React Native: Screen tree|Navigation config, API client, Env matrix
3. Flag any concern with 0 hits as a coverage gap.

Note findings for presentation in Step 6 under a "Codemap Coverage" section.

Do not auto-add missing sections — only surface the finding. Same deferral as Step 5d: section additions consume significant tokens and should be run as focused /codemap section <name> tasks in a separate session.

Step 5e: Cross-Project Pattern Detection

Skip this step entirely if projects_enabled: false or projects_list has fewer than 2 entries.

Scan {knowledge_folder}/projects/{*}/patterns/*.md (and optionally projects/{*}/decisions/*.md for cross-project decision detection) for files that may represent the same pattern across multiple projects.

Detection heuristics (consistent with /index Step 8d so the two skills surface the same candidates):

1. Filename similarity: Files with similar kebab-case names (e.g., state-management-patterns.md in two project subfolders). Case-insensitive equality of stem; allow minor variants (-patterns vs -pattern, plural vs singular).
2. Tag overlap: Files sharing 3+ tags excluding the project tags themselves (which are auto-derived from path per Decision #9).
3. Title/summary similarity: Files whose H1 (first # heading) shares 3+ significant terms (excluding stop words and project names).

Threshold: if a pattern appears in ≥projects_promotion_threshold projects (default 2), surface as a candidate.

For each candidate group, present to the user:

## Cross-Project Promotion Candidates

1. Pattern: "state-sync between AI and wizard"
   - projects/proj-a/patterns/state-sync.md (Last updated: 2026-04-12)
   - projects/proj-b/patterns/state-sync.md (Last updated: 2026-04-14)
   - Shared tags: state-management, agentic-ui
   - Suggested cross-project location: approaches/state-sync-between-ai-and-ui.md

   Promote to cross-project approach? (yes / no / skip)

If the user approves promotion:

1. Synthesize content from the project-specific files. Read each source file, identify common patterns, identify project-specific specializations. Draft a merged document with:
   • The shared pattern as the core content
   • Project-specific specializations called out as variants or notes
   • Original example references preserved with project attribution
2. Show the user the synthesized draft for review. Ask for edits or approval before writing.
3. Write the new cross-project file at the suggested location (typically approaches/{name}.md).
4. Add the originally_at: provenance frontmatter field to the new file:

---
Last updated: YYYY-MM-DD
tags: [tag1, tag2, ...]
originally_at: projects/proj-a/patterns/state-sync.md (merged with projects/proj-b/patterns/state-sync.md on YYYY-MM-DD during cross-project promotion)
---

This makes consolidations greppable (grep -r "originally_at:" knowledge/) and survives git history truncation.

5. Decide what to do with the source files — present to the user:

   • Remove — delete each source file (the cross-project file is the new home; project context is preserved via originally_at). (v2.15.2 note: this is verify-no-loss-compliant under the never-delete rule — the cross-project destination carries the full body with revisions/edits as needed, and originally_at: frontmatter provides the audit trail. Source-file deletion here is delete-after-move, not delete-without-preservation. No archive needed.)
   • Stub-and-reference — replace each source file with a 3-line redirect:

     # [Title]
     
     This pattern was promoted to [approaches/{name}.md](../../approaches/{name}.md) on YYYY-MM-DD as it was validated across multiple projects.

   • Keep — leave both source and cross-project files; useful when the project has unique context worth preserving alongside the shared pattern (rare)

   Default: stub-and-reference — preserves discoverability while avoiding duplication. Document the choice in Step 8's audit log entry.

6. Update index.md — append the new file to the appropriate tag sections; remove deleted source files from the index. (This happens automatically in Step 7b's index rebuild.)

If no candidates are detected, skip silently.

If candidates are detected but the user declines all promotions, note in Step 8's audit log entry: "N cross-project promotion candidates declined" (so they don't get re-suggested every audit unless evidence changes).

Step 6: Present Findings

Present a table with ALL files scanned and their category. Only show details for Category C items.

Output policy: emit every subsection defined below. Subsections with no findings must emit an explicit zero-state line (e.g., "Pending Insights: 0 — none pending.") rather than being omitted. The five subsections that explicitly permit silent omission (Pre-Compact Captures, Subagent Captures, Codemap Staleness, Codemap Coverage, Shared-Block Drift) are conditional-on-feature-presence — they omit when the feature doesn't apply to this project, not when findings are empty. Do not collapse or shorten the structured report in pursuit of brevity — empty sections with zero-count confirmations are informational signals that the audit ran the check.

Format:

## Knowledge Audit Results (YYYY-MM-DD)

**Last audit:** YYYY-MM-DD (N days ago)
**Files scanned:** X memory files, Y plan files

### Summary
- Category A (already captured): X files
- Category B (Claude-specific): Y files
- Category C (worth extracting): Z files

### Pending Insights (from insights-backlog.md)

For each insight entry:
- **Date / Project / Context:** from the entry header
- **Insight:** the bullet points
- **Suggested location:** where in the knowledge folder it should go (or "clear" if not worth keeping)

If none: emit "**Pending Insights:** 0 — none pending."

### Pending Ideas (from intake/ideas/)

Present ideas in their own section. **Sort stale entries first** (age > `ideas_staleness_threshold_days`, default 7). For each entry, show:
- Date, age annotation (`filed N days ago`), project tag, short title, type (feature/bug/design/refactor/workflow)
- Stale marker `[STALE — still relevant?]` appended when age > threshold
- Proposal and motivation (one-line summary if long)
- **Disposition prompt:** two-step format — top-level choice + Accept submenu

**Top-level options (always shown):**
- `Accept → [submenu]` — pick a destination from the per-idea submenu (computed per Step 2c2 detection probes)
- `Reject` — clear with one-line reason
- `Defer` — keep in place for next audit (disallowed implicitly for stale entries)
- `Reclassify` — move to insights/decisions/extraction backlog as observation

**Accept submenu (computed per idea):** always include `tracker | adr | backlog | rule`. Conditionally include `roadmap` if `ROADMAP.md` exists at the idea's project root or under `docs/`; `todo` if `TODO.md` exists similarly; `bundle` only on the lead entry of a detected cluster (and list cluster members inline).

For stale entries, prompt explicitly (don't allow implicit Defer). For non-stale entries, Defer is fine as a no-op.

Example output:

Pending Ideas (3)

• 2026-03-12 (35 days ago) — aria — refactor — simplify blueprint merge logic [STALE — still relevant?] Proposal: ... Accept → [tracker | adr | backlog | rule] / Reject / Defer / Reclassify? (no roadmap/todo: ROADMAP.md and TODO.md not found at aria project root or docs/)

• 2026-03-22 (25 days ago) — proj-a — bug — theme tokens missing from blueprint XYZ [STALE — still relevant?] Proposal: ... Accept → [tracker | roadmap | adr | backlog | rule] / Reject / Defer / Reclassify? (no todo: TODO.md not found) Hint: Use /foo-ticket to draft this as a ticket. (ticketing_plugins maps this project tag → foo-ticket)

• 2026-04-15 (1 day ago) — aria — feature — /setup diff prompts ahead vs diverged Cluster: bundle option available — also see "/setup state-aware second run" (2026-04-15) and "/setup test-mode skip re-decided" (2026-04-15) under aria project. Proposal: ... Accept → [tracker | adr | backlog | rule | bundle] / Reject / Defer / Reclassify?

When the user picks `Accept`, prompt: *"Destination? [tracker | roadmap | todo | adr | backlog | bundle | rule]"* (showing only the items in that idea's available submenu). Then route per the Step 2c2 specification.

**Submenu validation:** if the user names a destination that is **not** in this idea's available submenu (e.g., picks `roadmap` when ROADMAP.md doesn't exist for this project, or picks `bundle` on a non-clustered idea), do **not** auto-route to a fallback. Instead, re-prompt with a one-line explanation:

> *"`{destination}` is not available for this idea — {reason}. Pick from: [{available submenu}]."*

Reasons by destination:
- `roadmap` / `todo`: *"ROADMAP.md / TODO.md not found at {resolved project root} or its docs/ subdirectory"* (or *"project path unresolved"* per Step 2c2 resolution rules).
- `bundle`: *"this idea is not part of a detected cluster — file matches no other pending idea on project + ≥2 significant title words"*.

This makes the gap visible and forces an informed re-pick rather than silently routing to a destination the user didn't ask for.

**Between audits:** remind the user that `/context {project}` also surfaces pending ideas scoped to that project (informational, non-selectable) — for keeping the staged list visible between audit cycles without running a full review. Audit-time is for disposition; `/context` is for awareness.

If no ideas exist: emit "**Pending Ideas:** 0 — none pending."

### Pending Decisions (from decisions-backlog.md)

For each decision entry:
- **Date / Project(s) / Context:** from the entry header
- **Decision:** what was decided and why
- **Recommendation:** promote to ADR in `{knowledge_folder}/decisions/` (with suggested filename) or "clear" if already captured elsewhere

If none: emit "**Pending Decisions:** 0 — none pending."

### Pending Rules (from rules-backlog.md)

For each rule entry:
- **Date / Project(s) / Context:** from the entry header
- **Rule:** the proposed rule statement (and the "why" / "how to apply" lines if present)
- **Recommendation:** suggested promotion target — (a) **user memory** (`feedback_*.md` under the active project's `~/.claude/projects/{cwd-encoded}/memory/`) for personal/working-style rules that span projects; (b) **cross-project ARIA rule** (`{knowledge_folder}/rules/user-rules.md`) for ARIA-behavior rules that apply across all work; (c) **project-tier working rule** (`{knowledge_folder}/projects/{tag}/rules/working-rules.md` — projects tier only) for project-scoped discipline. Or "clear" if already captured elsewhere.

If none: emit "**Pending Rules:** 0 — none pending."

### Pre-Compact Captures (from intake/pre-c

*Truncated - read the full file at https://github.com/mikeprasad/aria-knowledge/blob/986165cdfe9aae5a19a43662f13870ce4d0e8699/plugin-openai-codex/skills/audit-knowledge/SKILL.md.*