decision-capture
Skill2 starsChanged 6 months agoMITView on GitHub
When the user wants to extract, review, or maintain project decisions from transcripts, meeting summaries, notes, emails, issue threads, docs, or chat logs. Reads `.agents/project-context.md` first when available, selectively ingests source material only when decision extraction is the task, and writes structured markdown decisions with source references.
5 other projects use a version of this.
Adopted by
Most recently taken up by
- bartoszarendt/agenticlooptheir own version, first seen Nov 14, 2026
- bartoszarendt/castworktheir own version, first seen Nov 8, 2026
- nearai/ironclawtheir own version, first seen Oct 8, 2026
- blonderoofrat/agent-skillstheir own version, first seen Jul 31, 2026
- sandst1/decision-capture-skilltheir own version, first seen Jun 17, 2026
Other versions5 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 5
- nearai/ironclaw★ 13ksame name
- sandst1/decision-capture-skill★ 4same name
- bartoszarendt/agenticloop★ 3same name
- bartoszarendt/castwork★ 3same name
- blonderoofrat/agent-skills★ 2same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- execution-traceSkill
- project-contextSkill
- requirements-from-decisionsSkill
- workspace-initSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
34 rules. 0 are common, 24 are distinctive, and 10 are very specific to this project.
0
Common
Most of the 5 edited versions we read keep these.
24
Distinctive
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Use this skill to capture:
- Distinctive: line 32
Do not assume the decision file belongs inside a production code repo.
- Distinctive: line 46
Read it before reviewing decision sources.
- Distinctive: line 48
Follow the project’s stated decision location if one exists.
- Very specific: line 49
If the project says there is no formal decision log yet, use .agents/decisions.md unless the user requests another path.
- Distinctive: line 51
If it does not exist:
- Distinctive: line 54
Do not invent project governance.
- Distinctive: line 61
Use the narrowest useful source set:
- Distinctive: line 69
Before reading many large files, state the intended source set and proceed if it matches the user’s request.
- Distinctive: line 85
Do not upgrade a candidate to accepted unless the source or user clearly confirms it.
- Distinctive: line 86
Treat “we should probably” / “I think” / “let’s consider” as candidate unless followed by approval.
- Distinctive: line 87
Treat explicit exclusions as accepted non-goal decisions when the source clearly confirms them.
- Distinctive: line 88
Keep open questions separate from decisions.
- Distinctive: line 90
Do not infer a historical decision's approver from the current project context.
- Very specific: line 139
Use existing canonical IDs when present, such as DL-001, ADR IDs, Jira IDs, or signed decision-log anchors.
- Very specific: line 140
Use D-001, D-002, etc. for accepted decisions only when there is no existing canonical ID.
- Very specific: line 141
Use C-001, C-002, etc. for candidate decisions.
- Very specific: line 142
Use X-001, X-002, etc. for deferred/rejected/superseded decisions.
- Very specific: line 143
Use Q-001, Q-002, etc. for open questions.
- Distinctive: line 145
Do not renumber existing decisions unless the user explicitly asks.
- Distinctive: line 149
After writing or updating decisions, summarize:
- Very specific: line 161
Read .agents/project-context.md before source material when available.
- Very specific: line 163
Do not paste large transcript excerpts into .agents/decisions.md.
- Distinctive: line 165
Do not copy private raw transcripts into the project workspace unless the user explicitly asks and the project permits it.
- Distinctive: line 166
Do not treat a transcript as authoritative if later email, issue, or approval notes supersede it.
- Distinctive: line 167
If two sources conflict, mark the item as candidate or open until resolved.
- Distinctive: line 168
If a decision affects scope, requirements, acceptance, pricing, timeline, privacy, security, or client approval, make that visible in notes.
- Distinctive: line 169
If implementation direction appears useful but is more specific than accepted decisions, keep it as a candidate and state what confirmation …
- Distinctive: line 184
Use the section headings from the template unless the user requests a different structure.
- Distinctive: line 185
Use markdown tables for all decision categories.
- Distinctive: line 186
Keep each row short; move nuance into notes only when needed.
- Very specific: line 187
Use stable status labels: Accepted, Candidate, Deferred, Rejected, Superseded, Open, Resolved.
- Very specific: line 188
Use date wording that preserves source confidence: YYYY-MM-DD for known decision dates, Indexed YYYY-MM-DD or See canonical source.
- Distinctive: line 189
Keep source refs inline in the row.
“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Decision Capture
You help users turn messy project source material into a compact, source-linked decision record.
This skill is for decision extraction and decision-log maintenance. It is not for creating broad project context, deriving requirements, or writing tickets. Start with .agents/project-context.md when it exists, then selectively read only the source material needed for the decision task.
What this skill does
Use this skill to capture:
- accepted decisions
- candidate decisions that need confirmation
- deferred or rejected options
- open questions that block decisions
- source references for each item
- owners or approvers when known
- changes to prior decisions when clearly stated
The output is structured markdown, usually at:
.agents/decisions.mdDo not assume the decision file belongs inside a production code repo. It may live in a project workspace above one or more repos.
Workflow
Step 1: Read project context first
Look for:
.agents/project-context.mdIf it exists:
- Read it before reviewing decision sources.
- Identify source systems, transcript locations, decision locations, review rules, and approval boundaries.
- Follow the project’s stated decision location if one exists.
- If the project says there is no formal decision log yet, use
.agents/decisions.mdunless the user requests another path.
If it does not exist:
- Continue only if the user supplied enough source material or source locations for decision capture.
- Do not invent project governance.
- Recommend creating project context afterwards if the decision output reveals recurring source systems or approval rules.
Step 2: Confirm the source budget
Decision capture may require reading transcripts, but only because this task is explicitly about decisions.
Use the narrowest useful source set:
- Existing
.agents/decisions.md, if present. - User-provided excerpt or meeting summary.
- A specific transcript, email thread, doc, issue, or chat link named by the user.
- A small batch of source files for a date range or milestone.
- Full transcript corpus only if the user explicitly asks for broad decision discovery.
Before reading many large files, state the intended source set and proceed if it matches the user’s request. If the request is broad but ambiguous, prefer the most recent or named source first.
Step 3: Classify decision-like material
Classify each item as one of:
| Status | Meaning |
| Accepted | The source clearly says the decision was made, approved, or agreed. |
| Candidate | The source implies a likely direction, but approval is unclear. |
| Deferred | The source says the decision was postponed or needs later review. |
| Rejected | The source says an option is out of scope or will not be pursued. |
| Superseded | A later decision replaces this item. |
Rules:
- Do not upgrade a candidate to accepted unless the source or user clearly confirms it.
- Treat “we should probably” / “I think” / “let’s consider” as candidate unless followed by approval.
- Treat explicit exclusions as accepted non-goal decisions when the source clearly confirms them.
- Keep open questions separate from decisions.
- Preserve uncertainty instead of smoothing it away.
- Do not infer a historical decision's approver from the current project context. If a canonical decision log is the only reviewed source, use the canonical log as owner/approver and avoid claiming a named person approved it unless the source says so.
- Distinguish decision dates from index/export dates. If a local index only shows when it was updated, write
See canonical source; local index updated YYYY-MM-DDrather than presenting the index date as the decision date. - Include adjacent accepted decisions only when they materially affect the requested scope. For example, if an editor decision touches persisted node creation or software configuration, include accepted schema decisions for node IDs or software field shape; do not broaden into unrelated scope.
Step 4: Write or update .agents/decisions.md
Use this structure:
# Decisions
Status: active
Last updated: YYYY-MM-DD
## Decision sources
| Source | Type | Date | Location | Notes |
|---|---|---|---|---|
If a source was requested but unavailable, include a source row or note that it was not reviewed. Make the note narrow to this run so it does not age into a permanent fact.
## Accepted decisions
| ID | Decision | Source | Date | Owner / approver | Notes |
|---|---|---|---|---|---|
## Candidate decisions
| ID | Candidate decision | Source | Date | Needs confirmation from | Notes |
|---|---|---|---|---|---|
## Deferred / rejected decisions
| ID | Status | Item | Source | Date | Notes |
|---|---|---|---|---|---|
## Open questions
| ID | Question | Source | Owner | Status | Notes |
|---|---|---|---|---|---|
## Change log
| Date | Change | Source |
|---|---|---|ID format:
- Use existing canonical IDs when present, such as
DL-001, ADR IDs, Jira IDs, or signed decision-log anchors. - Use
D-001,D-002, etc. for accepted decisions only when there is no existing canonical ID. - Use
C-001,C-002, etc. for candidate decisions. - Use
X-001,X-002, etc. for deferred/rejected/superseded decisions. - Use
Q-001,Q-002, etc. for open questions. - Preserve existing IDs when updating a file.
- Do not renumber existing decisions unless the user explicitly asks.
Step 5: Report the review cutline
After writing or updating decisions, summarize:
- sources reviewed
- accepted decisions captured
- candidate decisions needing confirmation
- rejected/deferred items
- open questions
- any source gaps or confidence issues
- recommended next skill, if useful
Source handling rules
- Read
.agents/project-context.mdbefore source material when available. - Preserve source links, filenames, transcript timestamps, issue numbers, email subjects, or doc titles when available.
- Do not paste large transcript excerpts into
.agents/decisions.md. - Short quotes are allowed only when they materially clarify a decision and are not sensitive.
- Do not copy private raw transcripts into the project workspace unless the user explicitly asks and the project permits it.
- Do not treat a transcript as authoritative if later email, issue, or approval notes supersede it.
- If two sources conflict, mark the item as candidate or open until resolved.
- If a decision affects scope, requirements, acceptance, pricing, timeline, privacy, security, or client approval, make that visible in notes.
- If implementation direction appears useful but is more specific than accepted decisions, keep it as a candidate and state what confirmation would promote it.
Output standard
A good .agents/decisions.md is:
- compact enough to read quickly
- structured enough for later skills to parse
- source-linked enough to audit
- conservative about acceptance status
- explicit about who needs to confirm unresolved items
- separate from raw transcripts and notes
Formatting rules:
- Use the section headings from the template unless the user requests a different structure.
- Use markdown tables for all decision categories.
- Keep each row short; move nuance into notes only when needed.
- Use stable status labels:
Accepted,Candidate,Deferred,Rejected,Superseded,Open,Resolved. - Use date wording that preserves source confidence:
YYYY-MM-DDfor known decision dates,Indexed YYYY-MM-DDorSee canonical source; local index updated YYYY-MM-DDfor index/export dates. - Keep source refs inline in the row.
Common pitfalls
- Treating every discussion point as a decision.
- Calling a decision accepted when the source only shows preference or brainstorming.
- Losing source references during summarization.
- Dumping transcript text into the decision file.
- Reading an entire transcript corpus when the user named one source.
- Creating a decision log in the production repo when the project context points to a workspace-level
.agentsdirectory. - Mixing requirements and implementation tasks into the decision log.
Verification checklist
Before finishing:
.agents/project-context.mdwas read when available.- Source set reviewed is explicit.
.agents/decisions.mdexists or the user declined creation.- Accepted decisions are separate from candidates.
- Open questions are separate from decisions.
- Source refs are present or marked
TBD. - Existing IDs were preserved on update.
- Canonical IDs and canonical-log authority were preserved without inventing named approvers.
- Index/export dates were not represented as decision dates unless the source supports that.
- No large raw transcript excerpts were copied accidentally.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

