Update the Knowledge Base

Flownix nodes are the team's living knowledge base. This skill keeps them trustworthy: content reflects reality, and decisions are captured. Prerequisite: flownix-basics.

When to use

• The implementation diverged from what a task/plan/feature/project spec says.
• A decision future readers must know was made (architecture, trade-off, convention).
• A task finished and produced an outcome or learning worth preserving.
• A node's content is outdated, wrong, or missing acceptance criteria.

Workflow

0. Load project context

cat .flownix 2>/dev/null || cat .ai-flow

Parse the YAML for project_id. Neither file exists → run flownix-init.

1. Load and assess

• get_node for current content and comments; get_tree if siblings/parents are affected.
• rag_query({ project_id, query: "<the topic>", k: 5 }) to find every other node carrying the same, now-wrong knowledge. Stale content ranks just as well as correct content, so a contradictory copy left behind poisons future retrieval. See flownix-rag-search.

2. Update the durable content

• Read spec_mode. For a doc node under strict: reread the doc, build its complete new body, check it with validate_spec, then propose_doc_delta (with the originating task/plan as source) and apply_doc_delta — do not call update_node_content on that doc. Otherwise update_node_content brings title/content in line with reality.
• Edit the spec — not just a comment — whenever the contract changed: scope, criteria, approach.
• Keep content clean Markdown: purpose, current state, acceptance criteria, open questions.
• If the update reveals the node touches a part of the system it isn't linked to, fix the binding with set_node_components (or create_component, then link). Docs included.

3. Capture the why as a comment

add_comment with [decision] (what was decided, the alternatives, the rationale) or [done] (outcome, learning). Content = what is true now; comments = how and why it got that way.

4. Propagate

• A decision that affects other nodes gets a brief [decision] comment on them too, or a follow-up task (plan-feature) — don't let knowledge rot in one place.
• add_tag for findability (decision, architecture).

Rules

• Never let content lie. Node content and comments feed the semantic index — a wrong spec doesn't just sit there, it gets retrieved and repeated by the next agent.
• Edits re-index automatically within seconds. Check rag_status if you need to know it caught up; never verify with rag_query.
• Record decisions while they're fresh — a decision not written down is lost.
• Prefer editing the spec over piling up contradictory comments.

The spec format

Behaviour is recorded in the OpenSpec format — ## Purpose, ### Requirement: <name> with a RFC 2119 keyword, #### Scenario: with GIVEN/WHEN/THEN — and only in it. Freeform prose about a contract is a defect, not a style choice.

Read flownix-write-spec and follow it for the format, validate_spec, propose_doc_delta and the human approval gate. Not restated here: the same block used to sit in five skills, and five copies drift.

Editing a doc node's behaviour section directly is not a shortcut around the delta: in spec_mode: strict the delta is what a task's closure rests on, and where require_proposal_approval is on it is also what a human approves before the work may start.