synthesis-kb-edit

Synthesis Knowledge-Base Editing

Run a complete knowledge-base edit in plain language while enforcing the repository's declared policy. The generic workflow lives here; repository specifics live only in .agents/knowledge-base.yaml.

Binding rules

1. Config decides; prose recollection does not. Pass the configuration gate below before anything else; a missing or invalid config stops the work, because every other rule reads it.
2. Editable/refused/generated path rules are mechanical gates. Write only where kb_config.py --resolve says editable; generated and refused are hard stops, and a request outside editable scope becomes a reviewer note.
3. One owning concept per fact. Search every existing mention before writing and never create a second concept for a fact an existing one owns.
4. One configured date field; no aliases. Frontmatter and taxonomy are single sources of truth: use only declared fields and controlled values, and remove conflicting body copies.
5. Validate before saving: the config check, the OKF validator, the consistency check and the configured confidentiality scanner. A protective control that cannot run blocks shipping.
6. Never bypass hooks, scanners, reviews, or branch protections, and never use --no-verify. A bypassed control protects nothing.
7. The index holds exactly this change. Never stage sibling-session work, and never discard or silently absorb unrelated edits.
8. Never merge a ship: pr edit from the editor workflow, and never commit it on the default branch; publishing belongs to the reviewer named in review.who_merges.
9. Claim the repository area on the synthesis coordination board before writing when concurrent root sessions are active.
10. Never force-push or rewrite shared history. A failed fast-forward stops and is surfaced.
11. This skill does not widen authority. Follow the current session's authorization rules for every commit, push and merge.

Contents

• references/edit-and-ship.md: the seven-step edit and ship workflow (preflight, find the owning concept, isolate, edit, validate with the exact commands, review and stage, ship) and the 1.0.0 hard invariants as written. Read it before any edit, and before shipping an existing edit.
• references/knowledge-base-config-v1.md: the complete .agents/knowledge-base.yaml contract. Read it when the config check fails or a key's meaning is unclear.
• references/coverage-map.md: where each part of the 1.0.0 text now lives.
• Configuration gate, Route by intent, Plain-language interaction, Synchronize after publication: below.

Configuration gate

Before interpreting or changing the repository:

1. Locate the Git root and read .agents/knowledge-base.yaml.

2. Run:

   python3 <skill-root>/scripts/kb_config.py <repo-root> --check-paths
   

3. Stop if the config is absent or invalid. Never infer a bundle, editable scope, generated output, confidentiality filter, Git host, or publishing policy.

4. Read notes and any configured review.setup_guide.

The complete contract is in references/knowledge-base-config-v1.md.

Route by intent

• Edit and ship: understand the requested change, find its owning concept, edit, validate, and follow the configured ship flow.
• Ship an existing edit: preserve the user's existing edits, validate their exact paths and contents, then follow the configured ship flow.
• Synchronize after publication: verify the review request is published, fast-forward the configured default branch, and remove the working branch only when Git confirms it is merged.

If intent is unclear, ask one plain-language question. Do not make a non-technical editor choose paths, branches, or Git commands.

Plain-language interaction

Translate a technical term the first time it matters:

• branch: a separate workspace copy
• commit: save the change as one labeled step
• push: upload the saved change
• pull request: a request to review and publish the change
• default branch: the shared published version
• frontmatter: the settings block at the top of a document

Narrate a state-changing action before it runs and report the outcome without dumping command output. Follow the current session's authorization rules; this skill does not widen authority.

Synchronize after publication

1. Verify the review request or branch is actually published.
2. Ensure the working tree is clean or isolate unrelated work.
3. Switch to default_branch and fast-forward from its configured remote.
4. Delete the local work branch only after Git confirms it is merged. Delete a remote branch only when repository policy and current authority permit it.
5. Re-run the config and OKF validators on the synchronized tree.

If fast-forwarding fails, stop and surface the divergence. Never force-push or rewrite shared history.