aria-knowledge

/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.

Runtime Gate (per ADR-094)

Canonical resolution: This is the Claude Code variant. When both plugin-claude-code and plugin-claude-cowork are loaded in the same session (most common in Claude Desktop), bare /audit-knowledge resolves to this skill — aria-knowledge (Code) is the canonical owner of all 24 dual-port skills per ADR-094 §Part 1. The Cowork variant is namespaced-only: /aria-cowork:audit-knowledge.

Before Step 0: Check that the Bash tool is available in this session. If Bash is NOT available (you are running in Claude Cowork or another non-Code runtime), surface the following notification and wait for explicit user confirmation:

⚠️ Runtime mismatch — you invoked aria-knowledge's /audit-knowledge from a non-Code runtime.

This variant scans ~/.claude/projects/{cwd}/memory/ and ~/.claude/plans/ via Bash — paths Cowork's persistent-grant model can't reach. For the Cowork-native variant (audits the attached folder's intake/ subfolder only), use /aria-cowork:audit-knowledge.

Use /aria-cowork:audit-knowledge instead? (y / n)

Wait for an explicit reply:

• y / yes — Use the Skill tool to invoke aria-cowork:audit-knowledge with the same arguments the user provided to this invocation. Do not proceed with this skill's steps; the cowork variant takes over and runs to completion. This is the default-yes path — auto-redirect is the helpful action.
• n / no — Proceed with this (aria-knowledge) variant anyway despite the runtime mismatch. The user has explicitly opted in.
• No response / any other reply — Treat as "do not proceed" and exit cleanly without running either variant.

This gate applies even when mode = auto per ADR-094 §Part 3. Auto mode's "implicit-yes on all gates" rule is suspended for the runtime-mismatch check — auto trusts that the user invoked the correct variant, and this gate enforces that precondition. All other auto-mode gates remain bypassed. The friction cost is now low: on y, the auto-redirect runs the correct variant with the original args.

If Bash is available, proceed to Step 0.

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.
3. 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)"
4. If user says yes → run the full /index logic (Steps 0-10 from the /index skill), then continue with Step 2
5. If user says no → continue with degraded checks (note in Step 6 output which checks were limited)
6. 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