| name | knowledge-compile |
| description | Compile source material from docs/raw/<topic>/ into a navigable wiki node at docs/research/<topic>.md. Use when source-material has accumulated and needs summarization with cross-refs to existing feature docs / RCAs / memory. |
| argument-hint | <topic-path-under-docs/raw> |
| context | fork |
| agent | general-purpose |
Knowledge Compile
Reads docs/raw/<topic>/, derives a wiki node at docs/research/<topic>.md with summary + sources + cross-references + key claims + open questions. Implements Phase 4 of ADR-010.
Input: topic path under docs/raw/ (e.g. tolkien/middle-earth-geography).
Output: docs/research/<basename>.md where <basename> is the leaf component (middle-earth-geography.md).
What this skill does (and doesn't)
Does:
- Inventories
docs/raw/<topic>/ recursively.
- Greps
docs/features/, docs/reviews/, docs/ai-includes/, docs/adrs/ for keyword matches to seed cross-references.
- Synthesizes a wiki node following the structure documented in
docs/research/README.md.
- Validates the output by running
/lint-docs --quick after writing.
- Regenerates backlinks so the new node is wired in immediately.
Doesn't:
- Modify anything in
docs/raw/. Source material is read-only from this skill's perspective.
- Edit existing feature docs, ADRs, or RCAs. Cross-references go in the research node, not retroactively in target docs (backlinks handle the reverse direction).
- Fetch new material from the web. The user is responsible for populating
docs/raw/ (via Obsidian Web Clipper or manual curation).
Phases
Phase 1: Inventory
Run the briefing probe:
python tools/compile_research.py "$ARGUMENTS"
This emits a markdown briefing with:
- Full file inventory of
docs/raw/<topic>/
- Keyword-matched candidate cross-references from existing docs
- A skeleton outline for the target research node
Read the output. If docs/raw/<topic>/ is empty, stop and tell the user to add source material first.
Phase 2: Read the raw material
Open each file in docs/raw/<topic>/. For text files, read the full contents (these should be small — large binaries don't belong in raw/, per docs/raw/README.md). Note for each:
- Provenance (who/what is the source, when)
- Key claims it makes
- Anything that contradicts other sources in the same topic dir
Phase 3: Audit the candidate cross-references
The probe's keyword-match candidates are candidates, not facts. For each:
- Skim the candidate doc and confirm the topic is genuinely relevant.
- Drop candidates that share only superficial keyword overlap.
- Add cross-references the probe missed — check memory file references (memory lives at the auto-memory path; reference memory entries by filename in prose).
Phase 4: Draft the research node
Write docs/research/<basename>.md following the structure in docs/research/README.md:
# <Title-Case Topic>
> Source materials: `docs/raw/<topic>/` — <N> files, last compiled <YYYY-MM-DD>
## Summary
<1-2 paragraphs: what does the raw material collectively say>
## Sources
- `docs/raw/<topic>/<file>` — <one-line description>
- ...
## Cross-references
- [features/<name>.md](../features/<name>.md) — <how the topic connects>
- [reviews/rca-<name>-<date>.md](../reviews/rca-<name>-<date>.md) — <past lesson>
- Memory: `feedback_<name>` — <relevant captured guidance>
## Key claims
- **<claim>** — source: `docs/raw/<topic>/<file>`. <Brief rationale.>
- ...
## Open questions
- <Gap in the source material>
- <Contradiction between sources>
- <Follow-up research that would strengthen this node>
Rules:
- Every claim must cite which raw file it came from (line-level if relevant). Knowledge without provenance is rumor.
- Cross-references use markdown links to existing repo files. Memory entries are mentioned by filename in prose (don't link to per-user home paths —
tools/lint_docs.py will flag those).
- The Open questions section is the most important. It's how the next compile pass knows what to focus on.
Phase 5: Wire it into the wiki
After writing the file:
python tools/lint_docs.py --quick
python tools/build_backlinks.py --dry-run
If lint reports dead links in the new node, fix them before applying backlinks. Then:
python tools/build_backlinks.py
Phase 6: Surface the result
Tell the user:
- The path of the new research node
- How many sources it summarized
- How many cross-references it wired
- The open-questions list (so they can add raw material to address gaps)
Do not commit. Leave that to the user.
Re-running on an existing topic
If docs/research/<topic>.md already exists, the skill overwrites it cleanly. The user can hand-edit the Open questions section between compile runs to refine focus; everything else is bot-authored and can be regenerated.
Out of scope (don't do these here)
- Don't fetch from the web. Web material goes through Obsidian Web Clipper into
docs/raw/<topic>/ first.
- Don't modify existing feature docs. If you find that a research node reveals a gap in a feature doc, surface it to the user; let them update the feature doc by hand.
- Don't lint outside the new node. Phase 5's lint pass is bounded to the dead-link probe; full-tree lint is
/lint-docs.
See also
