decision-record
Record decisions with rationale, alternatives, and consequences — the ADR pattern as a primitive. Use when a consequential choice is made — architecture, tooling, process, scope, trade-off. Capture WHY, not just WHAT.
- License 许可
- MIT
- 最近更新
- 2026-11-11
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- decision-record
- metadata
- { "processkit": { "id": "SKILL-decision-record", "uses": [ { "skill": "event-log", "purpose": "Log events to keep the audit trail accurate after every write." }, { "skill": "actor-profile", "purpose": "Resolve and validate Actor IDs referenced by this skill's entities." }, { "skill": "index-management", "purpose": "Query existing entities and keep the SQLite index fresh after writes." }, { "skill": "id-management", "purpose": "Allocate unique entity identifiers via central ID generation." } ], "layer": 2, "created": 1775433600000, "version": "1.0.0", "category": "processkit", "commands": [ { "args": "decision-title", "name": "pk-dec", "description": "Record a new architectural or product decision with the given title" }, { "args": "filter", "name": "pk-dec-find", "description": "Query existing decisions by keyword, status, or topic" } ], "provides": { "mcp_tools": [ "record_decision", "query_decisions", "link_decision", "supersede_decision" ], "templates": [ "decisionrecord" ], "primitives": [ "DecisionRecord" ] }, "apiVersion": "processkit.projectious.work/v2" } }
- description
- Record decisions with rationale, alternatives, and consequences — the ADR pattern as a primitive. Use when a consequential choice is made — architecture, tooling, process, scope, trade-off. Capture WHY, not just WHAT.
02 资源文件 7
- 资产文件assets/decisionrecord.yaml341 B
- 参考文档commands/pk-dec-find.md130 B
- 参考文档commands/pk-dec.md133 B
- 参考文档mcp/mcp-config.json213 B
- 参考文档mcp/SERVER.md2.7 KB
- 脚本mcp/server.py11.4 KB
- 脚本scripts/.gitkeep—
03 SKILL.md 正文
Decision Record
Intro
A DecisionRecord captures a single consequential choice: what was decided, why, what alternatives were rejected, and what consequences are expected. This is the classic Architecture Decision Record (ADR) pattern, promoted to a first-class primitive in processkit.
MCP server. This skill ships a self-contained MCP server at
mcp/server.py(PEP 723 script — requiresuvand Python ≥ 3.10 on PATH). Agent harnesses reach its tools by reading a single MCP config file at startup, so the contents ofmcp/mcp-config.jsonmust be merged into the harness's MCP config and placed at the harness-specific path before this skill is usable. If processkit was installed by an installer, that wiring is the installer's responsibility; if processkit was installed manually, the project owner must do it by hand.
Overview
When to record a decision
Record a decision when the choice:
- Has consequences someone will ask about in six months ("why are we using X?").
- Rules out real alternatives that took thought to reject.
- Affects more than one file, component, or person.
- Is the kind of thing that "we decided in a meeting" but nobody wrote down.
Don't record: trivial choices made inside a single function, preference calls with no downside, decisions already documented somewhere authoritative.
Shape
---
apiVersion: processkit.projectious.work/v2
kind: DecisionRecord
metadata:
id: DEC-steady-river
created: 2026-04-06T00:00:00Z
spec:
title: "Use official Python MCP SDK with uv PEP 723 inline dependencies"
state: accepted
context: "Skill MCP servers need a runtime. Options vary from zero-dep stdlib to full SDK."
decision: "Use the official mcp Python SDK, distributed as standalone scripts with PEP 723 inline deps, launched via uv."
rationale: |
- The SDK is the standard; rolling our own JSON-RPC means maintaining protocol code.
- PEP 723 + uv eliminates per-skill env setup; uv caching amortizes first-run cost.
- Container already has Python ≥3.10 and uv — no base image change.
alternatives:
- option: "Raw JSON-RPC with zero dependencies"
rejected_because: "Reimplements the protocol, fragile for complex servers."
- option: "Pydantic-only minimal server"
rejected_because: "Kept as escape hatch if container size becomes critical; not default."
consequences: |
- +300-400 MB image size per skill with MCP server.
- First-run 5-10s for uv resolution; cached thereafter.
- Escape hatch documented if size becomes an issue.
deciders: [ACTOR-owner, ACTOR-claude]
decided_at: 2026-04-05T00:00:00Z
---
Optional body: longer narrative, links to the discussion, related research.
Workflow
- Pick an ID:
DEC-<generated-id>. - Write a declarative
title— state the decision itself, not a question. - Fill in
context(what prompted this),decision(the chosen option),rationale(why). - List
alternativeswith explicitrejected_because— this is the part future-you will thank present-you for. - Write
consequences— what follows from this decision, positive and negative. - Set
state: proposedif still under discussion,acceptedif finalized. - Save to
context/decisions/. - Log
decision.created; later state changes usedecision.transitioned.
Superseding
When a decision is replaced by a later one:
- In the new DecisionRecord, set
spec.supersedes: DEC-<old-id>. - In the old DecisionRecord, set
spec.state: supersededandspec.superseded_by: DEC-<new-id>. - Log
decision.supersededreferencing both IDs.
Never delete or edit the old record. Its existence is why we can trace the evolution of the decision.
This skill also provides the /pk-dec and /pk-dec-find commands for
direct invocation — see commands/pk-dec.md and
commands/pk-dec-find.md.
Gotchas
Agent-specific failure modes — provider-neutral pause-and-self-check items:
- Recording a decision before it has actually been made. A proposal in a discussion is not a DecisionRecord. Open a Discussion if reasoning is still in flight; only record when the choice is settled. Recording too early creates a fictional history.
- Capturing WHAT but not WHY. A DecisionRecord without rationale is just a workitem in the wrong directory. The whole value of the ADR pattern is the reasoning trail — what was considered, why this was picked, what was rejected.
- Omitting the rejected alternatives. "We decided X" is half a decision; "We picked X over Y and Z because …" is a decision. Future-you needs the alternatives to know whether the call still holds when context changes.
- Editing an old DecisionRecord instead of superseding it.
Decisions are immutable history. If the call needs to change, write
a NEW DecisionRecord with
supersedes:pointing at the old one and set the old one's state tosuperseded. Never overwrite — the old reasoning is part of the audit trail. - Recording trivial choices as DecisionRecords. A DecisionRecord is overhead; reserve it for choices a future agent or human will ask about in six months. Variable naming inside one function is not a DecisionRecord.
- Putting the rationale in the Discussion body instead of the DecisionRecord. Discussions are pre-decisional reasoning; DecisionRecords are post-decisional summary. The rationale must be copied (not linked) into the DecisionRecord so the latter is self-contained when read in isolation.
- Hallucinating decision history when the user asks "what did we
decide about X". Run
query_decisionsandsearch_entitiesagainst the actual store before answering. Do not synthesize an answer from memory; it will be wrong.
Full reference
State machine
See src/primitives/state-machines/decisionrecord.yaml:
proposed → accepted → superseded (terminal)
↓
rejected (terminal)
rejected is for decisions considered and declined — kept for history.
superseded is for decisions replaced by a later one.
Full field list
See src/primitives/schemas/decisionrecord.yaml. Notable fields:
deciders: list of Actor IDs. Who agreed.supersedes/superseded_by: DEC IDs. Replacement chain.related_workitems: BACK IDs. Work that prompted or implements the decision.decided_at: when the decision was finalized. Distinct frommetadata.created(when the file was written).
Distinguishing decisions from discussions
A Discussion (separate primitive) is a multi-turn conversation exploring a question. A DecisionRecord is the crisp outcome. Workflow:
- Open a Discussion when a question arises.
- Explore, debate, research.
- When the group converges on an answer, write a DecisionRecord.
- Link the Discussion via
spec.related_discussions(cross-reference).
Not every discussion produces a decision; not every decision is preceded by a discussion.
Writing good titles
Good titles are declarative, active, and concrete:
- ✓ "Use official Python MCP SDK with uv PEP 723 inline dependencies"
- ✓ "Two-repo split: aibox + processkit"
- ✗ "Which MCP library to use?" (question, not decision)
- ✗ "Tooling update" (too vague)
- ✗ "Alice's proposal" (credits the person, not the decision)
Consequences that are honest
Future readers trust the decision record more when you write the real consequences, including the uncomfortable ones. "Costs 300-400 MB image size" builds more credibility than "some increase in container size."
Linking to workitems
When a decision prompts work to happen, link via spec.related_workitems:
spec:
related_workitems: [BACK-calm-fox, BACK-swift-oak]
This lets queries find "all work that implements DEC-foo" and "all decisions that motivated BACK-bar."
04 同仓库更多 Skills
standard-ui-design
暂无简介
standard-agent-use
Company standard for working with AI agents. Use when deciding what to delegate to agents, capturing open work, keeping agent memory or knowledge notes, improving an agent workflow, or introducing agent work in a team or for a client.
standard-agent-building
暂无简介
skill-management
Manage Skill package manifests as v1 ontology entities.
schema-management
Manage generated processkit schema contracts through deterministic MCP rebuild and inspection workflows.
proposition-management
Record claims, risks, beliefs, world facts, WSJF estimates, and assumptions through the Proposition interface.