dmthepm/commune-wiki/commune-write

commune-write

Grill, draft, refine. One piece per run. The draft goes into the real file in src/content/; the worktree is the staging area.

Run every command from the wiki root. Pass no --root. $COMMUNE is the path step 1 prints. Handoff file shapes: references/handoffs.md.

Rules

• Use the target note's title verbatim in [[Title]], with no display text

or pipe. Rewrite the sentence around the title.

• WRITING.md at the wiki root decides every sentence and every frontmatter

block. Read it first and read nothing else about voice. If it is missing, stop and say: "Run `commune-setup` first — this wiki has no `WRITING.md`."

• A note the dump means to publish gets visibility: public before you run

check. Notes default to private, and the graph cannot see a private note: check, related, gate and update all skip it, so a green check on a private draft proves nothing. When publish: false, say in one line that the note gets no graph verification, and do not pretend otherwise.

• Candidates in .connect.md are offers. A mention the draft ignores is not a

miss, and you never link something to raise a number.

• Rename or move a note only with $COMMUNE rename <from> <to>, never mv,

git mv, obsidian rename or a file tool. Those leave every [[link]] to the old name broken; rename rewrites them and keeps the URL. Add --dry-run first. When rename only changes a name's case in a git repository, it prints a git mv -f line on stderr; run that line so git records the new case.

• Never install anything. Do not commit the draft; commune-ship commits it.

The one exception is refine, which commits each correction on its own so a verdict can be reverted alone (references/refine.md).

Steps

1. Preflight and read. Run node scripts/preflight.mjs → $COMMUNE; stop

on exit 1 and show its line. Read, in order: WRITING.md, the dump file, dumps/<slug>.connect.md, and dumps/<slug>.answers.md if it exists. Pipe every --json payload through node scripts/preflight.mjs --schema.

1. Grill — when no answered round exists. Read references/forms.md

before every first round, then follow references/grill.md and references/research.md too when the dump might be research. Output: dumps/<slug>.answers.md with ## Settled and ## Round N — questions. Print the path and stop. Do not draft in the same turn.

1. Draft — when the newest round has answers under it. Read

references/forms.md, then the form from Settled or the round's answers; do not pick one here. No resolved form, or a target: in a collection that does not hold that form: ask in the next round, print the path, stop. Output: the file at target: in the dump, or a new file in src/content/<collection>/, named the way that collection already names its files — read one before you guess. Write ## Round N — decisions extracted into .answers.md first, then apply those decisions as a delta to the base named by base:. Frontmatter comes from WRITING.md's block for that collection, keys in its order. Append every file you touched to files: in .connect.md. Research follows references/research.md. It is the one exception to one piece per run: a dossier and its summary note, both in files:.

1. Verify. Run $COMMUNE check --json and compare finding identities (rule, file, target),

null for an absent target, against baseline.findings in .connect.md. Any new finding is yours to fix before you show anything; pre-existing findings are the baseline and are not. Then $COMMUNE graph related <target> --json for what the note now links.

1. Render the side by side. Run:

node scripts/review.mjs <base-ref> <target> --connect dumps/<slug>.connect.md --answers dumps/<slug>.answers.md --out dumps/<slug>.review.html Pass --out: the script's default is named after the note, not the dump. Print that path, then a short table of what changed in the graph — links added, links dropped, and for each dropped link what at_risk says it costs.

1. Hand off. Say: *"Answer in dumps/<slug>.answers.md, give me a

one-sentence correction, or say ship." On a correction, follow `references/refine.md` — same skill, next round. On "ship", say: "Run commune-ship."*

Stop conditions

• No WRITING.md → stop, name commune-setup.
• .connect.md has status: blocked → stop; commune-dump owns that.
• No answered round → you are in step 2, and stopping is the step.
• A new check finding you cannot fix → stop and say which line caused it.

Never show a review page with a broken link in it.