wiki-review

name

wiki-review

description

Arbitrates proposed wiki additions accumulated under `briefs/wiki-proposals/`. Walks each proposal with the human, asks merge / rewrite / discard / defer. Uses `.claude/.wiki-review-active` sentinel to authorise wiki/ writes during the session — the `block_wiki_write.py` PreToolUse hook detects the sentinel and allows the write. The single legitimate path through the wiki gate. Use when the user says "wiki review", "merge proposals", "review wiki proposals", or "/wiki-review".

Wiki review — merge proposals into the wiki

The wiki/ directory is the project's source of truth and is gate-locked by the block_wiki_write.py PreToolUse hook. This skill is the single legitimate path that bypasses the gate.

Prerequisites

• A wiki/ directory exists at the project root (the hook only fires on writes targeting wiki/**).
• One or more proposal files under briefs/wiki-proposals/*.md with frontmatter declaring target: (the wiki path they should land at).

If no proposals exist, exit with a one-line message: "No proposals in briefs/wiki-proposals/. Nothing to review."

Workflow

Step 1 — Inventory

List briefs/wiki-proposals/*.md. Skip:

• README.md
• Files starting with EXAMPLE-
• Subdirectories (e.g. archive/)

Report the count to the human: "N proposals to review."

Step 2 — Walk each proposal

For each proposal, in chronological order (filename starts with date):

1. Read the proposal. Extract target: from frontmatter (the wiki path it should land at) and the body.
2. Show a one-paragraph summary to the human (target path + 2-3 sentence gist of the proposal).
3. Ask: merge as-is / rewrite / discard / defer ?
4. Branch on the answer (Step 3, 4, 5, or 6).

Step 3 — Merge as-is

1. Create the sentinel: touch .claude/.wiki-review-active (an empty file is enough — the hook checks existence, not content).
2. Write the proposal body to the target wiki path declared in the frontmatter. Create parent directories if needed.
3. Delete the proposal file from briefs/wiki-proposals/.
4. Remove the sentinel: rm .claude/.wiki-review-active.

If the write fails or the user interrupts mid-merge: still remove the sentinel before exiting. A leftover sentinel disables the gate for the next session.

Step 4 — Rewrite

Ask the human for the changes (which sections, what tone, what to cut). Apply them to the proposal body in memory. Then proceed with Step 3 (merge the rewritten version, delete the original proposal).

Step 5 — Discard

Delete the proposal file. Do not write to wiki/. Move on.

Step 6 — Defer

Leave the proposal in place. Move on to the next.

Step 7 — End of run

After the last proposal:

1. Verify .claude/.wiki-review-active does not exist. Remove it if it does — its presence outside an active run is a bug that silently disables the wiki gate.
2. Report to the human: "N merged, M rewritten, K discarded, L deferred."

Why this gate exists

Direct writes to wiki/** are blocked by block_wiki_write.py. The wiki is the project's long-term memory: every entry must be reviewed by a human before it lands. Agents that learn something new propose via briefs/wiki-proposals/YYYY-MM-DD-<slug>.md; the human merges during /wiki-review.

Gotchas

• Never leave the sentinel in place outside an active run. If the skill exits mid-flight (crash, ctrl-c), the sentinel persists and disables the gate until manually removed.
• One sentinel for the whole session, not per proposal. Create it before the first merge, remove it after the last. Avoids touch/rm churn on N proposals.
• Frontmatter target: is required. If a proposal lacks it, ask the human where it should land before writing — don't guess.
• Discard is irreversible in this skill. The proposal file is deleted with no archive. If you want history, use defer instead.

STOP. Your deliverables: zero or more wiki entries created, plus the proposal files cleaned up.