Decrec

Pick a Route

Don’t add a step they didn’t name.

Decision-worthy

A fork is decision-worthy when all three are true:

• Alternatives: ≥2 credible paths were on the table (including do-nothing / defer)
• Consequence: the choice meaningfully constrains later work (architecture, product, process, a constraint)
• Future relevance: another human or agent could reasonably ask why did we do this?

Judge the direction, not the action. A sent email cannot be unsent — that alone is not Consequence.

Yes: Postgres vs Dynamo as system of record; public API contract vs internal-only; usage-based vs seat pricing.

No: tabs vs spaces; local names; Tailwind spacing; temporary debug logs; which of two independent tickets to implement today; easily reversible implementation details; copy/outreach/sequence trials; temporary workflows.

Recall, Capture, and Catalog share this bar. If uncertain: Recall does not Search; Capture does not offer; Catalog still lists the row.

Search

Topic in the ask (“why / what decisions about…”) and no DEC-n. Recency / what’s open with no topic → list_decisions (not this).

search_decisions (not list). Do not page list_decisions hoping titles match a theme.

One clear hit → use it. Several → show displayId + title + stage/snippet and ask. Don’t invent.

Hits are active only (archived omitted). If they asked about archived records, say so — do not treat empty or weak as “the org has none.” matchQuality: "weak" → say nothing ranked well; still show hits; do not claim the org has no decisions.

Hits are not a load and not an exploration payload (brief / recommendation on a hit are display-only). Load before update / admit / commit / decline / archive.

Recall

Search before reasoning — not a second lookup. Only when the matched row is Recall: this chat is Decision-worthy, they didn’t name a DEC-n, and they didn’t ask to explore or write. Before materially reconsidering a consequential product, technical, operational, or company direction, Search when doing so could prevent reopening settled reasoning or contradicting an existing commitment.

Do not Search before ordinary implementation, bugfixes, or refactors inside an already-chosen approach.

Follow-through differs from Search: don’t ask. One clear hit → Load. Several → Load the one that would constrain this ask. matchQuality: "weak" → proceed with reasoning. Cite prior decisions before proposing a conflicting path. A committed hit is a constraint unless they explicitly want to reopen. Do not auto-admit, update, explore, commit, or decline from Recall.

Skip (don’t Search): any other matched row; this chat already searched or loaded this topic; they named a DEC-n (Load that). MCP missing / unauthorized → continue their work; don’t Stop the whole turn.

Capture

When this chat produces a Decision-worthy choice, briefly offer to record it in DecRec. Do not record automatically. Thread “we decided / let’s go with / settled / ship it” is a preferred path to this offer, not a DecRec Commit. Do not skip as already done unless they say it is recorded elsewhere and should be skipped.

Finish the work they asked for first. Then offer only if it is Decision-worthy. If uncertain, do not offer — they can still ask to record.

Pasted dump / transcript → Catalog, not this. Already in Catalog / Shape / Explore / admit / update / commit / decline / archive for that fork → don’t re-offer. They declined or ignored this fork in this chat → don’t nag.

Offer in one sentence plus a working title (≤8 words). If they accept: Admit new + pick when a preferred path is in hand, else Admit framing only. Do not Explore unless they ask. If they decline or keep working, drop it.

Catalog

For a pasted Slack thread, meeting notes, email, or transcript: find Decision-worthy forks. If they pasted but asked to search, load, commit, decline, or archive, that row wins — not this. Explore / draft / admit stay on Catalog; continue only as far as they asked. Do not call tools. Do not Shape, Explore, or admit until they pick — and only as far as they asked.

Require the conversation text. If missing, ask once.

Include forks that are Decision-worthy and have a decision moment: open question, disagreement, blocked work, or apparent agreement / “we decided X” — even if the group leaned or “decided.”

Always include (high priority): moments that sound decided — capture them so the preferred path is not lost. Do not drop them as “already done” unless they say it is recorded elsewhere and should be skipped. Thread settled language is not a DecRec Commit.

Exclude: status/FYI with no fork, brainstorms with no pressure to choose, tasks with no strategic fork, vague aspirations, meta-process unless the decision is the process. Do not exclude because speakers used decided/settled language. If unsure a row is Decision-worthy, still show it — they pick.

If nothing qualifies, say so. Do not invent decisions.

Output a ranked table (max 7; merge duplicates; split only if independently decidable). Rank by: apparent agreement that still needs recording, then urgency × impact × how blocked the team is:

Then stop unless they already named #N / all top K, or skip catalog (they named one decision, or the thread has a single obvious fork) — then Shape that item.

On reply, Shape only the chosen numbers (one decision each; don’t merge). If they say proceed without picking, Shape the top item only. Admit or Explore a row only when that was in the ask.

Shape

Map the thread (and the open workspace, when the decision is about this project) into admit-ready fields. Read and cite the workspace (filename / path); do not edit. Do not invent stack, vendors, tenancy, or factual business metrics unless the thread, attachments, or workspace state them; proposing success metrics (what to measure) is allowed. One Shape → one decision (one admit). After Catalog, map only the selected row(s).

If several distinct decision candidates appear and this is a dumped conversation, Catalog instead of Shape. If they already named one fork, or Catalog was skipped, Shape that one — don’t merge forks into one brief, and don’t Shape/admit more than one unless they ask.

1. Map the brief:

• Title: prefer ≤8 words when you mint one; if they gave a title, use it verbatim (max 200 chars).
• Fields in this order: problem, evidenceSummary, assumptions, constraints, desiredOutcome, risks. Pain/outcome is not a pick — pick lives in synthesis. Thread “use X” → reframe problem/outcome; leave X for the pick.
• Empty fields: Tools require every field non-empty. Where the thread has nothing, use "unspecified" (do not invent). Prefer a single honest unknown in assumptions over stamping every thin field.
• Gap round if too thin to defend — especially missing problem or desiredOutcome: ask ≤3 bullets, stop and wait; on reply continue. Skip gap round when this Shape is the brief source for Explore (Densify covers thin intake).

2. If admitting a pick: send exploration: { synthesis, roles? }. Put optionsConsidered, preferredOption, tradeoffs, confidence, unresolvedQuestions, and disagreementHighlights inside synthesis — not on exploration. Prefer 2–3 optionsConsidered (max 4), each { title, summary, tradeoffs } from the thread; mutually distinct paths; preferredOption equals one title. confidence = medium if they stated the pick firmly, else low. Remaining synthesis strings from the thread, else "unspecified" — do not invent disagreements. Include roles as an array of { id, label, result } only if those essays already exist in thread — otherwise omit roles. Never partial. Skip Explore only when admitting without an explore ask and a preferred option plus ≥2 distinct alternatives already exist (including this chat’s Explore draft). Never invent a pick just to unlock admit. Never run Explore only to fill roles.
3. Do not call tools unless this Shape is for admit or update. Draft / frame only (no write verb) → stop after mapping; do not Create or Update. If admitting a new DEC: Create. If updating framing on an existing DEC: Update (include exploration if admitting a pick). If same brief, new pick: Follow-up. If Explore is next or already in progress, continue Explore with the mapped brief — do not end the skill.

Explore

Run the council in this chat with explore-prompts.md. If they asked to explore (from scratch, DEC-n, or re-explore), run even if a pick or loaded recommendation already exists. Never run Explore only to fill roles. When the decision is about this project, read and cite the open workspace. Do not invent stack, vendors, tenancy, or factual business metrics unless the brief, attachments, or workspace state them; proposing success metrics is allowed.

Council pick (before role passes):

• One-off roster named in this chat → use that roster; do not call list_councils; do not auto-save to Settings.
• Named saved council, or this chat already used one for this DEC → get_council with that name or id; skip list unless they asked to change.
• Else → list_councils, pick from the brief using name + role labels; then get_council with that councilId. None fit → get_council() with no args (org default, including focus). Do not infer default from isDefault on the list then get — use no-args get.

1. Brief source: from scratch → Shape from the thread (no gap round); existing DEC-n → Load. Stop if isLocked / !isApproved / activeExploration — locked cannot reopen in place; unapproved → approve at the url; in-flight → wait or cancel at the url. Else tip as-is (no reshape, no Densify — skip step 2).
2. Densify (from-scratch only): before role passes, assess intake gaps that would materially change options or confidence (including a missing problem or desiredOutcome; e.g. who it's for, hard limits, success criteria). This fills evidence / assumptions / constraints / risks so roles start fuller — it is not later openQuestions / unresolvedQuestions. If gaps remain: ask once (prefer ≤5; skip trivia), stop and wait; do not confirm the brief or run roles in the same turn. On reply, fold answers into the brief; skipped / “unknown” / “proceed anyway” → "unspecified". If already dense, skip this ask. Then show title + brief, wait for yes, then roles. If still blocked on naming any option, proceed and leave it in synthesis open questions. Otherwise do not interview beyond that.
3. Role passes (2–4 from the chosen council) — same title and brief each; clean context per pass (parallel isolated contexts when available, else sequential). See explore-prompts.md. Isolated contexts do not have this skill: send the explore-prompts.md role prompt (including Shared grounding) + title/brief + cited files. Substitute {Role label} + {focus} from get_council / the one-off, and {other seats} as one - {label} line per other role on that roster (labels only — do not paste sibling focus). They may read the workspace; they must not edit it.
4. Synthesis pass on verbatim role outputs (explore-prompts.md).
5. Show draft; stop unless also asked to admit, Commit, or Decline. Named Commit / Decline on this draft implies admit first — don’t Commit / Decline the loaded recommendation. When admitting after Explore: new DEC → Create with exploration; existing DEC, brief changed → Update with exploration; existing DEC, same brief → Follow-up. Then Commit / Decline only if that was in the ask. Send exploration with synthesis plus roles as an array of every council role { id, label, result } (never partial). Do not implement the pick unless they asked — exploring or recording is not a request to implement it.

Quality: Prefer 2–3 options (max 4). preferredOption must match one optionsConsidered[].title; options must be mutually distinct paths (not restatements of the preferred option). After role passes: put real cross-role conflict in disagreementHighlights when it exists; if independent passes agreed, say they agreed — do not invent a fight. Distinct paths do not require disagreement. When roles omitted, do not invent disagreement.

Load

Need DEC-n or UUID. Search/list hits are not a load — do not send a hit’s brief or recommendation as exploration or pins.

Tip = the current brief version (briefVersion + brief from this response). Update, Explore-existing, Follow-up, Commit, and Decline target that tip.

Call get_decision with decRef. Use this response for fail-fast, pins, url, and explorationRunId. recommendation is display-only (extra keys; not an exploration payload) — do not send it. Archive sends expectedDecisionVersion only (no briefVersion, no run id). Commit / Decline send pins plus explorationRunId (not the whole recommendation).

Reload (before Update / Follow-up / Commit / Decline only): if this chat already saw a briefVersion for that DEC, compare only that number to this response. Unchanged → brief text did not move; do not re-diff it. Changed → stop, show the six brief-field changes, ask. Load / discuss always reads the brief. Archive does not compare briefVersion.

If Load is the whole ask: discuss the tip in normal sentences (brief; recommendation.chosenOption if set). Asked to draft / frame / outline: Shape from the tip in chat — do not Update. Do not Report a write.

On tool error, branch on code (Errors).

Create

title + brief (+ exploration?) → call create_decision tool → Report → stop.

Writes an approved tip. Stage: brief-only → brief; +exploration → exploration. Keep displayId for a later Update, Follow-up, Commit, Decline, or Archive; always Load for pins. The response url is the DecRec UI for this decision.

On tool error, branch on code (Errors).

Update

Fail-fast: Load → stop if isLocked / activeExploration → if admitting a pick, also stop if !isApproved (approve at url) → Shape the new brief from the tip plus the requested changes (send all six fields) → pins from Load → call update_decision tool with decRef + pins + brief (+ exploration if admitting a pick) → Report → stop.

Writes a new tip. +exploration → stage exploration (owner only; current tip must be approved). Prior tip recommendation no longer applies. Same brief, new pick → Follow-up, not this path. Brief-only: any org member (draft tip allowed).

On tool error, branch on code (Errors).

Follow-up

Fail-fast: Load → stop if isLocked / !isApproved / activeExploration → pins from Load → call admit_exploration tool with decRef + pins + exploration → Report → stop.

Do not send recommendation as exploration. A Follow-up always writes a new run on the current approved tip and becomes the tip recommendation. Brief changed → Update, not Follow-up.

On tool error, branch on code (Errors).

Commit

Commit in this skill is DecRec only — not git commit. Take explorationRunId from recommendation (don’t invent; don’t send the whole object).

Fail-fast: Load → stop if isLocked / !isApproved / activeExploration / no recommendation → pins + explorationRunId from Load → call commit_decision tool with decRef + pins + explorationRunId → Report → stop.

On tool error, branch on code (Errors).

Decline

Decline is “we decided not to” (no Commitment row). Take explorationRunId from recommendation (don’t invent; don’t send the whole object).

Fail-fast: Load → stop if isLocked / !isApproved / activeExploration / no recommendation → pins + explorationRunId from Load → call decline_decision tool with decRef + pins + explorationRunId → Report → stop.

On tool error, branch on code (Errors).

Archive

Fail-fast: Load → stop if status=archived → expectedDecisionVersion from Load → call archive_decision tool with decRef + expectedDecisionVersion → Report → stop.

Committed or declined may still be archived (isLocked is not a stop). In-flight exploration is cancelled by Archive. Do not send briefVersion or explorationRunId.

On tool error, branch on code (Errors).

Errors

Tool failures return { "code": "pin_mismatch", "error": "…" }. Branch on code, not error text. MCP auth that never reaches a tool (not signed in / connection not allowed) is unauthorized. Schema/protocol errors with no code (empty strings, extra keys, partial roles) are invalid_body — fix; do not Update this skill.

Unknown code → Update this skill.

Tool calls

Nested fields follow each tool’s MCP schema. exploration is { synthesis, roles? } — do not hoist synthesis fields onto exploration. Empty strings fail — use "unspecified" (Shape). Pins and explorationRunId from Load — never invent. Omit unused keys (never {} or partial roles).

Top-level shapes:

Report

Do not paste pins, run ids, or brief-field JSON into the chat. Last briefVersion + six fields stay in session only so Reload can detect a brief move. Do not dump stage/status enums or run UUIDs.

Speak to the human in a few normal sentences (not a fence, not a labeled receipt):

• Link {displayId} to {url}
• What just happened, in product language (created, updated the brief, recorded a pick, committed, declined, archived)
• If a pick was written: the preferred option in plain words
• One optional next step only if it helps (e.g. open the URL to rename or attach evidence). Title, evidence, approve, and cancel in-flight are at the url — no skill tools for those. Do not list skill verbs.

When committed, declined, or archived: the record is locked — do not suggest editing title/evidence or further mutate unless they asked to archive.

Do not implement the pick unless they asked — recording is not a request to implement it. Do not chain commit, decline, or archive unless they asked.

On tool error, follow Errors. It is fine to show the error code; keep pins internal.

Examples (shape, not copy-paste): “Created DEC-12 with an approved brief.” / “DEC-11 is committed: keep offer-only capture for now.”

Update this skill

This copy's version is metadata.version in the frontmatter. Canonical package:

https://raw.githubusercontent.com/decrec-io/decrec-plugin/main/skills/decrec/

Do not fetch that unless they asked to update this skill, or they said yes after Tool errors.

Tool errors: Error whose code is internal, missing, or not in Errors. Not: any listed code, empty strings, partial roles. On unexpected errors: show the error, say this skill may be stale, ask to update; wait for yes. Then continue below.

1. Fetch {canonical}SKILL.md; read published metadata.version.
2. Same as this copy → already current; stop.
3. Different → show this vs published, then replace every file in this skill directory (SKILL.md, explore-prompts.md) from the canonical folder. Do not merge. Do not touch MCP configuration.

If fetch fails: stop; they replace the folder from wherever they installed this skill.

References

• explore-prompts.md — role + synthesis prompts
• MCP server decrec — provides get_decision, list_decisions, search_decisions, create_decision, update_decision, admit_exploration, commit_decision, decline_decision, archive_decision, list_councils, get_council, whoami tools