record-decision

name	record-decision
description	Record an architectural or design decision in the knowledge graph with full rationale. Use after making a significant choice that future developers should know about.
argument-hint	<brief description of the decision>

Record Decision: $ARGUMENTS

User input > Skill constraints > Trained defaults

For universal orchestration discipline reference /orchestrate. This skill is decision-recording-specific.

Record an architectural or design decision in the knowledge store. Good decisions are searchable months later — they tell future developers WHY things are the way they are.

Decisions are recorded only when the USER makes them. Never record_decision for Claude/agent implementation choices. Trained behavior: capture every reasoning step as a "decision." Wrong here — a record_decision node implies a user-owned choice with full alternatives considered. Agent-level implementation notes go to `thoughts(operation:"think")` and findings, not decision nodes. A decision without rationale is useless. A decision without alternatives is suspicious. Always capture the full context before recording. - WHAT was decided (specific, concrete) - WHY this option over alternatives (evidence-based) - WHAT ELSE was considered, and why rejected - WHAT CONSTRAINTS drove the decision Vague or incomplete decisions. Ask the user for the missing fields before recording. (Architectural clarification = legitimate touch point.)

Step 1: Clarify the Decision

If the description is vague, ask:

• What was decided?
• Why this option over alternatives?
• What else was considered and why rejected?
• What constraints drove the decision?

Optionally use thoughts(operation:"think") to record reasoning before committing — creates a chargeable trail linkable to the decision later.

Recording a decision IS evidence arriving — charge the thoughts that drove it. The hypotheses the session weighed on the way to this decision should not stay uncharged: charge each driving thought (polarity positive for the option chosen, negative for one the decision rejects), and cite the new decision node as evidence. A decision node itself is not chargeable (charges are thought-only); the chargeable trail is the thoughts behind it. Skipping this is the most common way load-bearing rationale ends up at zero charges.

Step 2: Search for Context

query({ "text": "$ARGUMENTS", "limit": 5 })
query({ "type": "decision" })

Look for: prior decisions on the same topic (this might supersede), findings that informed this decision, active projects/steps this decision relates to.

Step 3: Record the Decision

record_decision({
  "name": "Clear, searchable title",
  "description": "Full explanation + context",
  "choice": "What was decided — specific option",
  "rationale": "Why this option. Reference constraints, findings, requirements.",
  "alternatives": "What else considered. For each, explain why rejected."
})

Write as if someone searches "why did we choose X" or "how does Y work". Good: "Serve reflect modes from the loop cache instead of recomputing per call" Bad: "Database decision" Specific and concrete. Good: "Use interleaved bin packing with 200 max chunks and 40k token target" Bad: "Use batch processing" Reference evidence, not opinions. Good: "Benchmarks showed 3x throughput. See finding node abc123." Bad: "It seemed faster" Explain WHY each was rejected, not just list them. Good: "SQLite: rejected because it requires file locking, incompatible with concurrent MCP server access" Bad: "Also considered SQLite"

Step 4: Link Related Nodes

If Step 2 surfaced relations:

mutate({ "operation": "link", "from": "decision_id", "to": "related_id", "relationship": "informed-by" })
mutate({ "operation": "link", "from": "decision_id", "to": "old_decision_id", "relationship": "supersedes" })

Common relationships:

• informed-by — finding/research that led here
• supersedes — replaces previous decision
• relates-to — general association

Step 5: Confirm

Show recorded decision + connections + node ID for future reference.

Recording decisions without rationale — "we decided X" is not a decision record Skipping search for related context — decisions don't exist in isolation Vague titles — the title is what future searches match against Skipping alternatives — if there were no alternatives, was it really a decision?