context-audit

Context Audit

Purpose

This skill IS:

• Auditing context data points for CLEAR compliance
• Finding duplication and ownership conflicts across data points
• Identifying boundary violations between context areas
• Enforcing consistency in naming, format, and structure
• Providing prioritized findings with improvement recommendations

This skill IS NOT:

• Making changes to context (audit only -- findings guide manual fixes)
• A fix-it tool (this finds problems, you fix them based on findings)
• Checking markdown syntax (use doc-lint for that)
• Planning new work (use clear-planner for that)

Instructions

Step 1: Define Audit Scope

Pre-read (cheap, do this first): if docs/document-index.md exists, read it before asking the scope question. It gives you the canonical inventory of active data points by cluster, ownership, and last-updated date — enough to suggest a smart default scope (e.g., "you have 14 data points across 3 clusters; 4 haven't been touched in 90+ days — audit those?") instead of asking blind. If absent, fall back to the question below directly.

If not specified, use the AskUserQuestion tool:

• Question: "What should I audit?"
• Options:
• Specific area (e.g., competitive intelligence data points)
• Full architecture (all active data points — comprehensive)
• Recent changes (only docs modified recently)
• Cross-cutting concern (e.g., all pricing-related data points across clusters)

Step 2: Gather and Check Metadata

Context window strategy: For scopes with 20+ documents, delegate the metadata scanning to an explore agent. Keep the main window for CLEAR analysis (Step 3).

# For large scopes:
Agent (Explore): "Read all .md files in [scope]. Skip dot-prefixed files
(.session-diary.md, .wake-up-context.md, .onboarding-checklist.md) — these are
conventions, not managed data points. For each remaining file, extract YAML
frontmatter and check: all 7 required fields present? status valid? last-updated
within 90 days (180 days for _planned/)? Return a validation table."

For small scopes (< 20 files), scan directly:

1. Scan target area for all managed documents:

``bash Glob: [user-specified scope]/**/*.md Read: [identified files] ``

1. Check YAML frontmatter on every document:

Required fields (see docs/_bcos-framework/methodology/document-standards.md):

• name - present and non-empty
• type - valid value: context | process | policy | reference | playbook
• cluster - present and non-empty
• version - follows semantic versioning (x.y.z)
• status - valid value: draft | active | under-review | archived
• created - valid ISO date, immutable (should never change between versions)
• last-updated - valid ISO date, must be >= created date

1. Flag metadata issues:
2. Missing frontmatter entirely = CRITICAL
3. Missing required fields = HIGH
4. Stale last-updated (>90 days for active docs with a review-cycle) = MEDIUM
5. Docs in _planned/ use relaxed staleness: 180 days = MEDIUM
6. Missing optional fields = LOW (informational)
7. Docs in _planned/ with incomplete cross-references = LOW (informational, not error)

1. Folder-based checks:
2. Underscore opt-out convention: any top-level docs/_<name>/ folder is opted out of audit. Framework folders (_inbox/_planned/_archive/_collections/_bcos-framework) have specific handling below; user-created folders (e.g. _drafts/, _vendor-notes/) are skipped silently. The prefix is the rule, not a fixed list. See docs/_bcos-framework/guides/folder-conventions.md.
3. Document in docs/_planned/ older than 6 months → flag: "Consider promoting to active (move to docs/ root) or discarding"
4. Active document in docs/ that depends-on a _planned/ document → flag: "Forward-looking dependency — not yet real"
5. Files in docs/_inbox/ → skip audit entirely (raw material, no quality bar)
6. Files in docs/_archive/ → skip audit or report separately (historical, not active)
7. Files in docs/_collections/ → skip full CLEAR audit (no frontmatter required), but verify collection indexes are current if they exist
8. External reference data points (type: reference with an "External Source" section) → verify the source description is complete, don't try to validate external paths

1. Search for patterns:

``bash Grep: "TODO|FIXME" # Unresolved items Grep: [domain-specific terms] # Check consistency ``

Step 3: CLEAR Audit Categories

SAFETY RULE: When duplication is found, consolidate into the owning document first, then clean up the duplicate. Never delete without ensuring content lives in its authoritative home.

For background on consolidation principles, see docs/_bcos-framework/methodology/document-standards.md

Run all five audit categories against the scoped files.

A. Contextual Ownership Issues

Look for: multiple owners for same content, unclear responsibility (mixed domains in one doc), orphaned content (no consumers).

Example finding format:

ISSUE: "Company mission" defined in both company-overview.md AND strategic-plan.md
VIOLATION: No clear single owner
RESOLUTION: Designate one as owner, other links to it
EFFORT: LOW | VALUE: HIGH | PRIORITY: QUICK WIN

B. Linking Issues (Should Reference, Not Duplicate)

Look for: duplicated information across data points, copy-paste between docs, inconsistent cross-reference format (relative vs absolute links).

C. Elimination Issues (Remove Duplication)

Look for: same content in multiple places, redundant data points covering same concept, hardcoded values repeated across docs. Resolution is always: extract to single authority, others reference it.

D. Alignment Issues (Consistency Problems)

Look for: naming inconsistency (e.g., market_category vs marketCategory), format differences (tables vs lists for same content type), structure inconsistency in frontmatter.

E. Refinement Issues (Clarity Problems)

Look for: overly complex data points (500+ lines covering multiple concepts -- split them), vague language ("various market factors"), missing maintenance metadata (no last-updated or review-cycle).

Step 4: Technical Debt Identification

Search for debt markers:

Grep: "TODO"
Grep: "FIXME"
Grep: "OUTDATED"
Grep: "DEPRECATED"

Categorize debt:

## Technical Debt

### Active TODOs
- X total found
- Y urgent (>6 months old)
- Z recent (<2 months)

### Stale Content
- Documents not updated in >6 months
- Broken cross-references
- Orphaned sections

Step 5: Priority Matrix

Score each issue: Priority = (Impact x Frequency) / (Effort x Risk)

| Impact Level | Score | Effort Level | Score | |-------------|-------|-------------|-------| | CRITICAL (blocks context delivery) | 10 | Quick (< 1 hour) | 0.5 | | HIGH (causes wrong decisions) | 7 | Medium (1-4 hours) | 2 | | MEDIUM (slows consumers) | 5 | Large (1+ day) | 8 | | LOW (minor inconvenience) | 2 | | |

Classify into quadrants: QUICK WINS (high value, low effort -- do first), BIG WINS (high value, high effort -- plan carefully), LOW PRIORITY, AVOID.

Step 6: Generate Output

Produce a report with these sections:

1. Executive Summary -- total issues, critical count, quick win count
2. CLEAR Analysis -- one subsection per category (C/L/E/A/R) with findings
3. Priority Matrix -- issues sorted into quadrants
4. Recommendations -- immediate actions, this sprint, ongoing

Severity Levels

| Severity | Description | Action Timeline | | ------------ | --------------------------------------------- | ----------------- | | CRITICAL | Boundary violation, wrong information served | Fix immediately | | HIGH | Duplication causing divergence, broken links | Fix this sprint | | **MEDIU