| name | compare-doc-corpora |
| description | "WHAT: compare two documentation corpora and produce a structured gap/overlap analysis — what ideas in A are present/partial/absent in B, what B has that A lacks, where they agree vs diverge. WHEN: when you need to compare a reference/older corpus against a current one (e.g. an old design corpus vs our vision layer), find gaps, or reconcile two bodies of docs (any of)." |
PROMPT
You compare TWO documentation corpora and produce a structured gap/overlap analysis. `CORPUS_A` is the
REFERENCE (here: an older design/research corpus). `CORPUS_B` is our CURRENT layer (here: `docs/vision/.md`
= ideas/decisions/envisioned-not-built for a codebase). Goal: which ideas in A are captured / partial /
absent in B, what B has that A lacks, and where they agree vs diverge/contradict.
- `SYSTEM` = {the system being compared, e.g. soma | dragonbones}
- `CORPUS_A_DIR` = {path to the reference corpus}
- `CORPUS_B_DIR` = {path to our current/vision layer}
- `OUTPUT_FILE` = {path to write the comparison artifact}
0. FIRST check each corpus for a PRE-BUILT map — a `summaries/`, `neighborhood*`, `index`, `_MANIFEST`, `00_MASTER_SUMMARY`, or `OVERVIEW` layer. If present, THAT is the topic map: read it first, use it as the backbone, and only drill into raw files for specific citations. Don't re-derive a map that already exists.
1. Build CORPUS_A's TOPIC MAP (from its summaries layer if present, else every `.md`, recurse): each major idea/theme → 1-line gloss + `(fileA:section)`.
2. Build CORPUS_B's TOPIC MAP likewise.
3. For each major idea in A, classify against B: `PRESENT` (cite B file) | `PARTIAL` (cite + what's missing) | `ABSENT`.
4. List ideas in B NOT in A (new / diverged since A).
5. Flag `AGREE` vs `DIVERGE/CONTRADICT` pairs — cite BOTH sides.
6. Write `OUTPUT_FILE` (format below). Cite BOTH sides for every mapping (`fileA:section ↔ fileB:section`).
- Cite both sides for every mapping; quote a short snippet as evidence.
- **CITE-SCOPE (critical): every B-cite MUST be a string actually greppable in a file UNDER `CORPUS_B_DIR`.
`grep` it before you write it. NEVER cite code, IMPL/mirror docs, rules, or any other layer as if it
were in B.** If an A-idea is realized in code/IMPL but is NOT in the B layer, that is `ABSENT` (in B),
noted as "realized in code/IMPL, NOT in {B layer}" — that is a FINDING (graduated or undocumented),
NOT `PRESENT`. Same rule for A-cites: greppable under `CORPUS_A_DIR` or don't cite it.
- If a mapping is unsure, mark `UNCERTAIN` — do NOT force it.
- Never invent content in either corpus. If you didn't finish reading something, say so.
- Counts must be real command output (`find … | wc -l`), not estimates.
<output_format>
Write OUTPUT_FILE as markdown:
# {SYSTEM}: {CORPUS_A} ↔ {CORPUS_B}
## A topic map — [idea — gloss — (fileA)]
## B topic map — [idea — gloss — (fileB)]
## Classification — table [idea | PRESENT|PARTIAL|ABSENT | A-cite | B-cite | note]
## Gaps: in A, not in B — candidate vision(m) additions, each with (fileA:section) + 1-line why-it-matters
## In B, not in A — new since A
## Agree vs Diverge — table [pair | A-says | B-says | verdict]
## Confidence + what wasn't fully read
Then RETURN a short summary: counts (present/partial/absent), top 5 gaps, top divergences, confidence.
</output_format>
