Lightweight knowledge compounding system. Retrieve first, write only when it is worth it, and prefer updating existing knowledge over creating more noise.
Preamble: see templates/preamble.md
Retrieve before write. Skip is a valid outcome. Write only when the insight is non-obvious, verified, and likely to recur.
Responsible for: retrieval, worthiness judgment, overlap scoring, write/update/skip decision, discoverability check. Not responsible for: documentation that is not yet stable, replacing release or docs-writer.
Knowledge enters only after release is complete. Do not enter while work continues.
_PF_CLI="${PRIMEFLOW_CLI:-./primeflow}"
_RELEASE_ESCALATE=$($_PF_CLI state get release_escalate 2>/dev/null | tr -d '"')
_LAST_SKILL=$($_PF_CLI state get last_skill 2>/dev/null | tr -d '"')
echo "Last skill: $_LAST_SKILL | Release escalate: $_RELEASE_ESCALATE"
Knowledge is worth writing when ALL of these are true:
| Condition | Check |
|---|---|
| Non-trivial | not a typo fix, config toggle, or obvious mistake |
| Solved + verified | release completed, verify evidence exists |
| Non-obvious root cause or pattern | a reasonable engineer would not immediately see it |
| Likely to recur | same problem category will appear again in planning, review, diagnose, or release |
skipSearch docs/solutions/ for overlapping knowledge using the CLI.
_PF_CLI="${PRIMEFLOW_CLI:-./primeflow}"
_KEYWORDS="${KEYWORDS:?set KEYWORDS to search terms}"
# CLI-powered search with scoring
$_PF_CLI knowledge search $_KEYWORDS 2>/dev/null || echo "No knowledge artifacts found."
docs/solutions/For each candidate, read frontmatter (first 15 lines) and score:
| Dimension | Match scoring |
|---|---|
| Problem statement overlap | +1 |
| Root cause overlap | +1 |
| Solution overlap | +1 |
| Referenced files overlap | +1 |
| Prevention rule overlap | +1 |
| Total overlap | Decision |
|---|---|
| 4-5 | update — modify existing doc |
| 2-3 | create with caution — reference existing doc |
| 0-1 | create — genuinely new pattern |
No artifact written. This is the correct outcome for trivial or obvious work.
$_PF_CLI state set last_decision "knowledge-skip" >/dev/null
Open the existing doc, add new information under the appropriate section, update the date field in frontmatter.
# Frontmatter update for the existing file:
# - add new keywords if the new case reveals them
# - update date to current date
# - do not remove existing content, only add or refine
Write a new file using the appropriate track template.
Bug track (for resolved problems):
---