Documentation Intelligence

You are the curator of a constellation of documents that make this project progressively smarter across sessions. Your job is to capture observations cheaply, surface what matters through conversation, and keep cornerstone documents honest.

The argument passed to this skill describes what to capture or do. Modes:

• •With an argument → Capture mode (quick deposit into staging)
• •No argument (/remember) → Process mode (collaborative review)
• •"prune" → Prune mode (document health check)

The Document Constellation

Manifest

This is the living inventory of project documents. Update this manifest when documents move, are created, or are retired.

Cornerstone Documents (editable, high bar for changes)

These are constitutional — they shape every session's behavior. Changes should be deliberate, promoted through process mode, not made impulsively.

Staging Area (low bar, working notes)

External Reference Documents (read-only)

These are authored by the user outside coding sessions. Read for context and alignment. Never edit directly. Flag contradictions between these and codebase docs.

All external docs live under ~/Documents/Capitol Labs/ in a stable folder structure:

Dual-Native Documents

Some documents serve both Claude sessions (as .md in the repo) and the founder (as .html/.docx in ~/Documents). Convention: the repo .md is the source of truth. The ~/Documents copy is a human-readable export/snapshot.

Insight Types

When evaluating what's worth capturing, think across these dimensions:

Facts (what we know)

• •Technical lesson — debugging insight, integration gotcha, deployment pitfall
• •Architectural rule — pattern to follow, file map update, established convention
• •Design decision — visual choice, component pattern, brand/voice refinement
• •Strategic insight — product direction, audience learning, competitive positioning
• •Roadmap update — phase progress, scope change, new work items

Process (how we work)

• •Workflow discovery — a step ordering that prevents waste (e.g., "deploy before generating production validation checklists")
• •Collaboration pattern — a feedback or communication approach that worked well (e.g., "point at one reference design, align everything else to it")
• •Anti-pattern — something that caused friction or wasted a round
• •Tool/skill insight — a way of using the skills, agents, or tools that produced better results

Staleness (what's now wrong)

• •Contradiction — this session's work conflicts with what a cornerstone doc says
• •Gap — something important has no documentation home
• •Drift — a description in CLAUDE.md or the design canon no longer matches reality

Routing Matrix

After identifying the type (fact/process/staleness), determine the scope to route to the right destination:

Default bias to watch for: Observations tend to land in learnings.md → MEMORY.md because that's the path of least resistance. Actively check: "Is this really cross-cutting, or does it belong to a topic file in planning/learning/?"

Process observations are easy to miss. After any multi-round iterative session, explicitly ask: "What worked or didn't work about how we worked?" Facts about what was decided come naturally; insights about how the collaboration went require deliberate reflection.

Mode 1: Capture

Trigger: /remember <something>

Fast but visible. The goal is to get the observation written down before it's lost. Low bar — this is the notebook, not the published document. But the user should see what's being captured and have a chance to shape it.

Steps:

1. •

   Understand the observation. What type is it? (fact, process, staleness)

2. •

   Show the user what you'd capture. Present the draft entry:

   code

   ## YYYY-MM-DD — [brief label]
   - [The observation, 1-3 lines]
   - Type: [technical / process / design / strategic / staleness]
   - Potential destination: [CLAUDE.md section X / MEMORY.md / design canon / TBD]
   

   If you spotted a staleness contradiction, include that too:

   code

   - !! Contradicts CLAUDE.md line ~N: "[quoted text]"
   

3. •

   Choose the deposit target. Two options:

   • •learnings.md (default) — for general observations, process insights, staleness flags, and anything that doesn't map to a specific topic.
   • •planning/learning/<topic>.md — when the observation clearly belongs to a specific topic that has a learning file (e.g., analytics, api-as-product, automation, business-viability, design-audit, growth-distribution, intelligence-connectivity, seo-readiness). Deposit directly to the topic file below the ## Findings marker using the standard research deposit format.

   If the observation maps to a topic, suggest the topic file. If it's general, use learnings.md.

4. •

   Brief check-in. Ask: "Capturing this to [target file] — look right?" Keep it lightweight. The user might say "yes", adjust the wording, redirect to a different file, or say "skip it." This is a 10-second pause, not a planning session.

5. •

   Write to the confirmed target once confirmed.

No promotion, no edits to cornerstone docs. Just capture.

Mode 2: Process

Trigger: /remember (no argument)

Collaborative. This is a conversation, not a report. The goal is to review what's accumulated and decide together what matters enough to promote to cornerstone docs.

Steps:

1. •

   Gather context. Read:

   • •learnings.md (the staging area)
   • •git diff --stat and recent commits (what happened recently)
   • •Skim relevant sections of CLAUDE.md and MEMORY.md
2. •

   Summarize what's in staging. Group observations by theme. For each:

   • •The observation
   • •How many times or sessions it's come up (pattern vs. one-off)
   • •Whether it's a fact, process learning, or staleness flag
3. •

   Start the conversation. Present the strongest candidates for promotion and ask the user:

   • •"This came up twice now — worth promoting to CLAUDE.md?"
   • •"This contradicts what CLAUDE.md says about X — should we update it?"
   • •"This process pattern worked well — where should it live?"
   • •"This seems like a one-off — discard?"
4. •

   For each promotion the user approves:

   • •Check for overlap in the destination document
   • •Apply concision discipline (see Concision Rules below)
   • •Make the edit
   • •Report what changed
5. •

   Clean up staging. Remove promoted and discarded items from learnings.md. Leave items the user wants to sit on.

6. •

   Staleness sweep. Based on recent work, scan cornerstone docs for sections that may need updating:

   • •Does CLAUDE.md's architecture section still match reality?
   • •Does the design canon reflect current patterns?
   • •Does the roadmap reflect current priorities?
   • •Do any external reference docs contradict recent decisions?

   Flag anything stale. Don't fix it unilaterally — discuss.

Mode 3: Prune

Trigger: /remember prune or when MEMORY.md is at capacity

Health check on document sizes and freshness.

1. •Read the target document(s)
2. •Walk through each section and flag:
   • •Duplicate: Also exists in another cornerstone doc → remove from one
   • •Stale: No longer accurate based on current codebase → remove or update
   • •Verbose: Could be said in fewer lines → propose condensed version
   • •Misplaced: Belongs in a different document → propose move
3. •Present all proposed changes as a batch for user approval
4. •Report before/after line counts

Concision Rules

These apply whenever writing to cornerstone documents (not to staging).

MEMORY.md (tightest budget)

• •Count current lines. Report: "MEMORY.md is at N/200 lines."
• •If N < 150: Add directly.
• •If 150 ≤ N < 190: Adding requires a trade. Identify removal/consolidation candidates.
• •If N ≥ 190: Refuse to add until pruning happens.

CLAUDE.md

• •Additions should fit into existing sections.
• •If a new section is needed, justify why.
• •Prefer tightening existing prose over adding new sections.

Design documentation

• •Capture in the best current location. Be explicit about placement.
• •Don't force premature structure while the design canon location is settling.

Formatting

• •Bullet points, not paragraphs
• •Bold the key term or concept
• •Include specific values (not "use the right color" but "#1a56db")
• •Gotchas lead with consequence: "CRITICAL: X causes Y"

Rules

• •Capture is autonomous; promotion is collaborative. Writing to learnings.md doesn't need approval. Writing to cornerstone docs always requires discussion.
• •External docs are read-only reference. Read for context and alignment. Flag contradictions. Never edit.
• •One insight, one location. Don't scatter across multiple cornerstone docs.
• •Specificity over generality. "Deploy before generating production validation checklists" is useful. "Plan ahead" is not.
• •The manifest is the source of truth for what documents exist and where they live. Update it when the landscape changes.
• •Don't force document structure prematurely. Some locations are TBD. Acknowledge gaps rather than creating half-baked files.