agentleFS
house-of-giantshouse-of-giants/projectskills/skills/decision-capture/SKILL.md

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

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
  1. Distinctive:

    Use this skill to capture:

    line 16
  2. Distinctive:

    Do not assume the decision file belongs inside a production code repo.

    line 32
  3. Distinctive:

    Read it before reviewing decision sources.

    line 46
  4. Distinctive:

    Follow the project’s stated decision location if one exists.

    line 48
  5. Very specific:

    If the project says there is no formal decision log yet, use .agents/decisions.md unless the user requests another path.

    line 49
  6. Distinctive:

    If it does not exist:

    line 51
  7. Distinctive:

    Do not invent project governance.

    line 54
  8. Distinctive:

    Use the narrowest useful source set:

    line 61
  9. Distinctive:

    Before reading many large files, state the intended source set and proceed if it matches the user’s request.

    line 69
  10. Distinctive:

    Do not upgrade a candidate to accepted unless the source or user clearly confirms it.

    line 85
  11. Distinctive:

    Treat “we should probably” / “I think” / “let’s consider” as candidate unless followed by approval.

    line 86
  12. Distinctive:

    Treat explicit exclusions as accepted non-goal decisions when the source clearly confirms them.

    line 87
  13. Distinctive:

    Keep open questions separate from decisions.

    line 88
  14. Distinctive:

    Do not infer a historical decision's approver from the current project context.

    line 90
  15. Very specific:

    Use existing canonical IDs when present, such as DL-001, ADR IDs, Jira IDs, or signed decision-log anchors.

    line 139
  16. Very specific:

    Use D-001, D-002, etc. for accepted decisions only when there is no existing canonical ID.

    line 140
  17. Very specific:

    Use C-001, C-002, etc. for candidate decisions.

    line 141
  18. Very specific:

    Use X-001, X-002, etc. for deferred/rejected/superseded decisions.

    line 142
  19. Very specific:

    Use Q-001, Q-002, etc. for open questions.

    line 143
  20. Distinctive:

    Do not renumber existing decisions unless the user explicitly asks.

    line 145
  21. Distinctive:

    After writing or updating decisions, summarize:

    line 149
  22. Very specific:

    Read .agents/project-context.md before source material when available.

    line 161
  23. Very specific:

    Do not paste large transcript excerpts into .agents/decisions.md.

    line 163
  24. Distinctive:

    Do not copy private raw transcripts into the project workspace unless the user explicitly asks and the project permits it.

    line 165
  25. Distinctive:

    Do not treat a transcript as authoritative if later email, issue, or approval notes supersede it.

    line 166
  26. Distinctive:

    If two sources conflict, mark the item as candidate or open until resolved.

    line 167
  27. Distinctive:

    If a decision affects scope, requirements, acceptance, pricing, timeline, privacy, security, or client approval, make that visible in notes.

    line 168
  28. Distinctive:

    If implementation direction appears useful but is more specific than accepted decisions, keep it as a candidate and state what confirmation …

    line 169
  29. Distinctive:

    Use the section headings from the template unless the user requests a different structure.

    line 184
  30. Distinctive:

    Use markdown tables for all decision categories.

    line 185
  31. Distinctive:

    Keep each row short; move nuance into notes only when needed.

    line 186
  32. Very specific:

    Use stable status labels: Accepted, Candidate, Deferred, Rejected, Superseded, Open, Resolved.

    line 187
  33. Very specific:

    Use date wording that preserves source confidence: YYYY-MM-DD for known decision dates, Indexed YYYY-MM-DD or See canonical source.

    line 188
  34. Distinctive:

    Keep source refs inline in the row.

    line 189

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.md

Do 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.md

If it exists:

  1. Read it before reviewing decision sources.
  2. Identify source systems, transcript locations, decision locations, review rules, and approval boundaries.
  3. Follow the project’s stated decision location if one exists.
  4. If the project says there is no formal decision log yet, use .agents/decisions.md unless the user requests another path.

If it does not exist:

  1. Continue only if the user supplied enough source material or source locations for decision capture.
  2. Do not invent project governance.
  3. 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:

  1. Existing .agents/decisions.md, if present.
  2. User-provided excerpt or meeting summary.
  3. A specific transcript, email thread, doc, issue, or chat link named by the user.
  4. A small batch of source files for a date range or milestone.
  5. 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:

StatusMeaning
AcceptedThe source clearly says the decision was made, approved, or agreed.
CandidateThe source implies a likely direction, but approval is unclear.
DeferredThe source says the decision was postponed or needs later review.
RejectedThe source says an option is out of scope or will not be pursued.
SupersededA 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-DD rather 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.md before 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-DD for known decision dates, Indexed YYYY-MM-DD or See canonical source; local index updated YYYY-MM-DD for 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 .agents directory.
  • Mixing requirements and implementation tasks into the decision log.

Verification checklist

Before finishing:

  • .agents/project-context.md was read when available.
  • Source set reviewed is explicit.
  • .agents/decisions.md exists 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.