How to Write Meta-Analysis Docs

Canonical Location

<project>/docs/meta-analysis/

Pick one location per project and use it consistently — not scattered across different app folders, and not memory files. One convention in use was api/docs/meta-analysis/ (the backend repo, since that's where most of the investigated systems lived); use whatever this project's own docs root is.

---

Filename Format (EXACT)

{YYYY-MM-DD}_{subject}_{method}_{trigger}.md

Segment	Format	Examples
date	YYYY-MM-DD	2026-02-06
subject	kebab-case, the system/feature analyzed	user-simulator, login-flow, access-tiers
method	kebab-case, how the analysis was done	conversation-mining, state-audit, code-tracing, failure-analysis
trigger	kebab-case, why it was created	skill-creation, bug-investigation, design-review, incident-response

Real Examples

2026-02-06_user-simulator_conversation-mining_skill-creation.md
2026-02-06_new-user-state-audit.md
2026-02-07_login-flow_code-tracing_redirect-bug.md
2026-02-10_access-tiers_failure-analysis_incident-response.md

Naming Rules

• All segments joined by _ (underscore)
• Within each segment, words joined by - (hyphen)
• Date always first
• Subject always second
• Method and trigger can be combined if the filename would be too long: {date}_{subject}_{combined-context}.md
• Keep filenames under 80 characters

---

Document Structure (EXACT)

Every meta-analysis MUST follow this template:

# {Title} — {Subtitle}

**Date:** YYYY-MM-DD
**Tags:** comma, separated, keywords
**Context:** One sentence explaining what triggered this analysis
**When Invoked:** When should future agents read this document?

---

## EXECUTIVE SUMMARY

2-3 sentences. What was found. Why it matters.

---

## {Numbered sections with findings}

### Each section should:
- State what was investigated
- Show what was found (with code references, quotes, or evidence)
- State the conclusion or resolved intent

---

## ANTI-PATTERNS / LESSONS LEARNED

What went wrong. What to avoid. Table format preferred.

---

**End of Analysis**
**Source:** {where the data came from}
**Files analyzed:** {count or list}

Required Header Fields

Field	Required	Purpose
Date	Yes	When the analysis was performed
Tags	Yes	Keywords for searchability
Context	Yes	What triggered this analysis (one sentence)
When Invoked	Yes	Tells future agents WHEN to read this doc

---

When to Create a Meta-Analysis

Create one when you:

1. Mine conversation logs — Extract user directives, design decisions, frustrations from Claude Code history
2. Audit system state — Trace what code ACTUALLY does vs what it's SUPPOSED to do (like a "new-user-state-audit")
3. Investigate a failure — Root-cause analysis after something broke
4. Research for skill creation — Deep dive before writing a skill file
5. Architectural review — Map data flow, dependencies, or integration points

Do NOT create one for:

• Simple bug fixes (use whatever system log this project already has)
• Feature requests (use a proposal, if this project tracks those)
• Quick notes (a short compaction record is enough — see agentic-session-compactions)

---

After Creating: OPTIONAL — Make It Discoverable

CRITICAL: The full document is the source of truth. NEVER reduce, summarize, or strip detail from the meta-analysis itself. The document should contain the COMPLETE analysis with all nuance, code references, edge cases, and reasoning. Length is a feature, not a bug — these are deep audits, not summaries.

Optionally, after writing the full doc, create a lightweight pointer to it so a later agent can discover it exists without already knowing the filename. That pointer is ADDITIVE — it does NOT replace the full doc.

If institutional-memory search is set up (see /alignment-harness:harness-setup — one setup used a searchable memory index), add 2-5 index entries pointing to the full doc:

• context: "When an agent needs to understand {specific topic covered in the doc}"
• lesson: "See full analysis at: <project>/docs/meta-analysis/{filename}.md — section '{section name}' covers {brief pointer}"
• tags: Relevant keywords
• event_type: intent, pattern, or error

If no such index is set up, the fallback is that the doc lives at a predictable, greppable path (the filename convention above exists specifically so ls/grep across the meta-analysis folder finds it) — mention its existence and path in whatever session compaction covers this work (see agentic-session-compactions), so a later session's search of past compactions surfaces it.

Every pointer, wherever it lives, MUST reference the full doc path so agents always drill into the complete analysis. The goal is discoverability, NOT reduction. An agent searching "vision payment flow bugs" should find a pointer that leads them to the full 400-line document — not a 3-sentence summary that strips all the nuance out.

---

Optional: A Structured Findings Store

For findings that need structured tracking (confidence scores, verdicts, measurements over time, linked decisions), a markdown doc alone isn't ideal — you want something queryable. If your project has (or you build) a small structured-findings store — a database table, or even a JSON-lines file under alignment-harness records findings — use it alongside the markdown doc:

• Record: title, research type, hypothesis, findings, verdict (e.g. confirmed/refuted/inconclusive), confidence (0-100)
• Search it before starting new research, so you don't duplicate a finding someone already recorded
• For major analyses, create the markdown doc AND a findings-store entry that links to it

If you don't have one set up, skip this — the markdown doc alone is still complete and correct; it's just not queryable by confidence score.

• When to use markdown: Deep narrative audits, architectural investigations, conversation mining (length is a feature)
• When to use a structured findings store: Hypothesis tracking with verdicts, time-series measurements, decision audit trails, anything agents need to query programmatically

Cross-References

• Local records folders (compactions, findings, etc.) → alignment-harness records <kind> (see agentic-session-compactions)
• Skill files for this plugin live at plugin/skills/{skill-name}/SKILL.md