Update Knowledge Base

Type: operation

Intent

Every entry reduces the number of questions that need a human to answer.

Steps

1. Identify whether this is a new entry or an update to an existing one. For an update, read the existing file first.
2. Determine the type: decisions, or operations.
3. Draft the entry. For decisions: id matches filename; decision is a single clear statement; why explains the consequence of not following it; links are organic and unidirectional — each note answers 'how does this linked decision specifically affect or constrain this decision?'; violations are specific enough to detect in a code review; files list only files where a reviewer would look to verify the decision is respected.
4. For links: only add one if the note would change how someone implements or reviews this decision. Drop it if the relationship is obvious from context alone.
5. Present the complete draft to the user before writing any file.
6. Write the file.
7. Run the static validation scripts: pwsh -NoProfile -ExecutionPolicy Bypass -File .github/utils/confim-knowledge-graph-schema.ps1, then pwsh -NoProfile -ExecutionPolicy Bypass -File .github/utils/confirm-knowledge-graph-integrity.ps1. CI runs semantic validation for changed decisions with .github/utils/confirm-knowledge-graph-semantic.ps1. Fix any errors before proceeding.
8. Open a PR. CI runs static tests and LLM checks on changed decisions — the PR cannot merge until it passes.

Files

• knowledge-graph/guiding-principles/
• knowledge-graph/decisions/
• knowledge-graph/operations/

Violations

• writing a file before presenting a draft to the user
• adding a bidirectional link
• link note that does not answer 'how does this linked decision specifically affect or constrain this decision?'
• violation that restates the decision instead of describing a detectable breach

← Back to operations