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.

Configuration gate

Before interpreting or changing the repository:

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

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

1. Stop if the config is absent or invalid. Never infer a bundle, editable

scope, generated output, confidentiality filter, Git host, or publishing policy.

1. Read notes and any configured review.setup_guide.

The complete contract is in [references/knowledge-base-config-v1.md](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.

Edit and ship workflow

1. Preflight

1. Verify the Git root, configured remote, and configured host.
2. Check the working tree and index. Identify every existing edit and whether

it belongs to this request. Never discard or silently absorb unrelated work.

1. Verify the configured confidentiality control exists and is operational.

A protective control that cannot run blocks shipping.

1. Fetch the configured remote so the workspace starts from current remote

state.

For githost: bitbucket, use synthesis-bitbucket or the applicable private companion skill. For githost: github, use the available GitHub CLI or connector. Host mechanics do not belong in this skill.

2. Find the owning concept

Use topic_routing to select likely directories, then search the configured bundle for every existing mention of the affected entity or fact. Present candidate concepts by title. Do not create a second concept when an existing one owns the fact.

For durable facts learned during the current session, compose with synthesis-knowledge-capture: scan every mention, reconcile conflicts, and preserve provenance before entering this ship workflow.

Classify every candidate path before writing:

python3 <skill-root>/scripts/kb_config.py <repo-root> --resolve <repo-relative-path>

Write only when the result is editable. Treat generated and refused as hard stops. Capture a request outside editable scope as a reviewer note rather than changing the file.

3. Isolate the work

For ship: pr, create one short-lived branch from the fetched remote default branch using the configured branch_prefix. Never commit the edit on the default branch. Carry pre-existing intended edits onto that branch without moving unrelated work.

For ship: direct, use the repository's declared branching rules. Direct shipping still requires the authority granted by the user and surrounding instructions.

4. Edit with the declared schema

• Match the concept's established voice and structure.
• Keep one concept per file.
• Use only frontmatter fields declared by frontmatter.required and

frontmatter.house, plus fields already allowed by the repository's taxonomy.

• Use frontmatter.date_field as the only last-update field. Do not add an

alias such as last_updated when the config declares timestamp.

• Read taxonomy_path before selecting type, tags, status, or placement.

Never invent a controlled value.

• Never hand-edit a configured generated artifact.

5. Validate before saving

Run all three layers:

python3 <skill-root>/scripts/kb_config.py <repo-root> --check-paths
python3 <synthesis-okf-root>/scripts/okf_validate.py <bundle-path> --summary --check-links
python3 <synthesis-okf-root>/scripts/okf_consistency.py <repo-root> <touched-path>...

The consistency check enforces the configured frontmatter schema and detects duplicate or conflicting inline metadata, invalid taxonomy values, title/heading drift, and naming or placement problems. Resolve every CONFLICT and DUPLICATE; review every WARN.

Then run the configured confidentiality scanner against the exact staged added lines. Read its pattern source at runtime; never copy its terms into this public skill. If the scanner or hook cannot run, stop. Never bypass a match or use --no-verify.

6. Review and save exactly the intended files

Show:

• what changed, concept by concept;
• which configured schema and taxonomy were applied;
• the conformance, consistency, link, and confidentiality results;
• any reviewer notes for requests outside editable scope.

Stage only the listed editable files. Before committing, inspect both git status --short and git diff --cached --name-only; the index must contain exactly this change. Use a generic commit message when repository policy requires it.

7. Ship through the declared policy

• ship: pr: push only the working branch and open a review request against

defaultbranch. Use review.defaultreviewers when configured. Never merge the editor's own request. Report the request number, URL, responsible publisher from review.who_merges, and what automation runs after merge.

• ship: direct: push only when current authority and repository rules

permit it. Verify the remote branch afterward.

Use repository-relative paths in outward-facing text. Do not expose local absolute paths, secrets, scanner patterns, or AI attribution unless the user explicitly requests attribution.

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.

1. 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.

Hard invariants

• Config decides; prose recollection does not.
• Claim the repository area on the synthesis coordination board before

writing when concurrent root sessions are active.

• Editable/refused/generated path rules are mechanical gates.
• One configured date field; no aliases.
• Frontmatter and taxonomy are single sources of truth; remove conflicting

body copies.

• Never bypass hooks, scanners, reviews, or branch protections.
• Never merge a ship: pr edit from the editor workflow.
• Never stage sibling-session work.