<!-- SYNCED COPY — do not edit here. Canonical: common-docs/skills/docs/SKILL.md This file is distributed to every consuming repo by common-docs/meta/scripts/sync_skills.py. Edit the canonical, run the sync, and commit each repo. Edits made here are overwritten and lost. -->

docs — the procedure

The rules are the rules of this bundle and the domain tree. Read both once; this skill is only how to apply them.

1. Place it

1. Find the subject's node in the domain tree (Domain → Feature → Sub-feature). The doc goes in that node's folder under systems/, or in a temporary projects/ folder only while work is tangled across two or more homes.
2. No node fits: add a feature where its domain clearly holds it (same commit, tell Arman), or propose the change in chat. Never invent a domain.
3. Something already covers the subject? Edit that file. Never create a parallel doc.
4. A repo keeps only rules tied to a code path in that directory (a trap, an import ban, a file map). Everything with meaning (what, why, status, plans, contracts, vision) lives in the node.

Done when: the target path is a node folder and no other file covers the subject.

2. Edit = whole-document review

1. Read the whole doc, not the section you came for.
2. Verify every claim you keep or add against live code, the DB, or git. A doc's own "verified" is not evidence. What cannot be checked here is marked UNVERIFIABLE — <what would prove it>.
3. Put the change where it belongs and merge in place: no addenda, no "Update:" blocks, no history, no changelog. Two lines saying one thing become one.
4. Cut what a frontier model already knows and what a command or file read reveals.
5. Never lose a rule: tightening keeps every invariant, path and pointer. Removing a rule is something you say out loud in your report.

Done when: the doc reads as one voice and every claim in it is currently true.

3. Dedupe and verify (one subject)

1. Census. Grep the subject's terms across common-docs and every repo it touches; follow one ring of links. List every file that makes claims about it.
2. Elect the survivor: the node's file from step 1.
3. Classify each disagreement: fact vs fact → reality decides, fix the loser; doc vs Arman's words → his words win, and code that drifted from them is a finding, not a doc fix; his words vs his words, or a disagreement about meaning → step 6, never resolved by you.
4. Move, never copy. One source file at a time: merge its unique truth into the survivor, git rm the source, repoint every inbound reference in every repo, commit all of it in one command. A file never exists in two places across a commit.
5. Prove it. For every deleted path, grep all repos plus common-docs: it comes back empty.

Never touch: generated files, a .md that code reads (grep .py/.ts for its name first), a published package README, inbox/, a repo's .arman/. A spotted duplicate that is not blocking you is still yours: run this section or dispatch it, never just report it.

4. Clean up as you go

Working notes belong in your project or node; nobody cleans them but you and the daily sweep. Each time a step finishes, in the same commit:

• Status: the step becomes one line on its board or main doc ("P27 cutover: landed").
• Resume point: one line ("next: steps 2 and 3"); delete it when the lane closes.
• Evidence: say how to rerun it (the command); keep only what a later decision needs. Censuses, scans, logs and batch-by-batch verification notes are not kept once read.
• Arman's words go to the node's VISION.md (§5). Anything for him is shown in the chat.
• Clean-up-later notes: working material you must keep for now gets one line at its top saying when and how to cut it ("Once Meet ships, cut to what the spec lacks"). The daily sweep honors and acts on these notes.
• Finished work shrinks to a status phrase ("Gmail: live"); finished projects, closed handoffs and stale plans are deleted, never archived. Git holds history.

5. Arman's words

Any verbatim quote of Arman found outside a VISION.md moves, verbatim and dated, into the closest node's VISION.md (create it with type: Vision, authority: owner if missing), and the source line is cut. An agent's paraphrase attributed to him is deleted. Never rewrite, trim or "fix" existing VISION content. You never set authority: owner on your own writing.

6. Conflicts

A disagreement about intent or a ruling: one or two sentences in /operations/conflicts.md, then ask Arman in chat. When he answers: delete the entry, apply the answer, tell him how many remain.

7. Repo pointer lines

Every repo that touches the node gets ONE line, in that feature's FEATURE.md or else the repo CLAUDE.md, never a stub file and never restated content: Cross-repo system-of-record: /Users/armanisadeghi/code/common-docs/<path> — read it before touching this feature in ANY repo. A renamed or deleted doc orphans its pointers: grep every repo for the old path in the same session.

Repo checks after a doc change: aidream python3 scripts/check_doc_links.py (--all for package CLAUDE.md, PRINCIPLES.md, FOUND_DEFECTS.md, skills) and python3 scripts/check_docs_guards.py; matrx-frontend pnpm check:docs-guards and pnpm check:doc-claims. FOUND_DEFECTS.md IDs: defect ownership § Entry IDs.

8. Finish

1. Frontmatter with a non-empty type on every new .md; bundle-relative links; the folder's index.md updated.
2. python3 meta/scripts/okf_lint.py exits 0. Editing a SKILL.md → also the skill-authoring rules and python3 meta/scripts/skill_descriptions.py lint.
3. Fresh-reader review for guidance you wrote (CLAUDE.md, SKILL.md, STATE, FEATURE, memory): dispatch one fresh standard agent with only the file paths and reviewer-brief.md sent verbatim. Apply each CUT, REWRITE, MOVE; reject one only with a factual reason; answer each ASK from live evidence; turn a GUARD into code or a feedback item.
4. Commit by pathspec, git pull --rebase, push. Unpushed docs do not exist.

Daily sweep (the docs-steward schedule)

The sweep cleans what agents left behind while the work is still fresh. Commit message carries the scorecard (no log file).

• Yesterday's changes first: every doc changed in the last 24 hours (git log --since=24.hours --name-only). For each: apply §4 — finished steps become status lines, regenerable evidence goes, resume points for closed lanes go, Arman's words move to VISION.md, duplicates merge (§3). Keep anything a live lane, an open decision or a running script needs; when unsure, keep it and list it in the commit message.
• Large binaries and source data added that day go to file storage and are linked (how).
• Instructions that make agents write logs: if a skill, brief or plan told an agent to keep a log, evidence dump or per-event record, fix the instruction to §4, not just the file.
• okf_lint.py to zero; sync_skills.py --check.
• Inbox: each new item is dispositioned per /inbox/README.md; nothing in inbox/ is ever deleted.
• Conflicts: settled entries in /operations/conflicts.md are deleted; the rest read in seconds.
• Commit, push.

Old skill names

Old	Now
docs-steward	Daily sweep
cross-repo-docs, context-docs	§1, §2, §7, §8
dedupe-and-verify, doc-convergence, consolidate	§3–§5
future-reader-review	§8.3