metis-reconcile

name	metis-reconcile
description	Read the docs corpus and produce SYNTHESIS.md, INDEX.md, CONTRADICTIONS.md, and QUESTIONS.md in .metis/.

$metis-reconcile

Read everything under docs/. Produce four reconcile artifacts: .metis/SYNTHESIS.md, .metis/INDEX.md, .metis/CONTRADICTIONS.md, .metis/QUESTIONS.md.

Preflight

Run this skill's references/reconcile-preflight.sh before reading. It exits non-zero if docs/ is missing (surface the error and stop). Otherwise it reports STATUS (fresh / rereconcile), SIZE_CLASS (small / medium / large), and counts for the corpus and any prior items.

On SIZE_CLASS=large, apply the slicing guidance in this skill's references/reconciling-docs.md.

Load

• The source docs under docs/.
• On rereconcile, the prior .metis/CONTRADICTIONS.md and .metis/QUESTIONS.md. Re-reconcile preserves prior items and re-checks them against the current corpus (per this skill's references/reconciling-docs.md) rather than starting over.

Do not load

• .metis/RESOLVED.md.
• .metis/BUILD.md.

Read first

This skill's references/reconciling-docs.md — read before drafting any of the output artifacts.

Write scope

Four files in .metis/, all pre-created as stubs by the preflight so they exist before any write and Edit can target them on the first run.

Cadence — write across the passes, not in a terminal batch. Per this skill's references/reconciling-docs.md the artifacts take shape while you read: INDEX.md is the concept map built during the first pass (an index under construction is what makes terminology drift surface), and SYNTHESIS.md is the own-words summary whose not-yet-writable sentences force out Q items. CONTRADICTIONS.md and QUESTIONS.md accrue as items surface during the cross-referential read. Deferring all four to one sweep after the last doc is the sequential-skim failure mode the reference warns against — it reads less than it looks.

Write each artifact in its own step, and Read a file before the first Write/Edit that touches it — Claude Code refuses to overwrite a file it has not read this session, so a read-then-write keeps every write valid on the first attempt and isolates any failure to a single file.

• .metis/SYNTHESIS.md — full Write, regenerated from the current corpus rather than patched.
• .metis/INDEX.md — built during the first pass. On STATUS=fresh, grow it from the stub; on STATUS=rereconcile, prefer Edit: add, update, or remove individual entries surgically and leave unchanged entries in place.
• .metis/CONTRADICTIONS.md — same Edit-preferred discipline on rereconcile. Preserve items marked stale. Re-emitting unchanged items as Write output is the cost we're avoiding.
• .metis/QUESTIONS.md — same treatment as CONTRADICTIONS.md.

Do not write to .metis/RESOLVED.md, any source doc under docs/, or .metis/BUILD.md.

Invocation prompt

Trailing prompt: see this skill's references/command-prompts.md.

Return

One message to the user:

• Files written — four paths with item counts per CONTRADICTIONS.md / QUESTIONS.md (open / deferred / stale).
• Coverage — which docs were read in full vs. sliced, and any passages deliberately deferred to a later pass. On SIZE_CLASS=large, include the completeness caveat here.
• Next step — $metis-walk-open-items when there are open or stale items; $metis-build-spec when the open set is empty.