Skip to main content

Decision record — discussion → durable record → tasks

This skill takes a discussion that reached decisions and turns it into a durable record in bewith-dev/bewith-docs, then offers to turn its action items into GitHub issues via breakdown.

It is the intake step that sits above tasks: a discussion produces decisions, the decisions are recorded once, and tasks are generated from that record. Design docs come later — per task, downstream, after research — not here. A decision record is deliberately light and is not research output.

discussion + decisions  →  decision record (this skill)  →  /breakdown → tasks  →  (per task) deep-research → design doc → issues → DoD

Sibling to draft-proposal. That skill captures an idea to triage. This skill captures a decision already made. Same worktree-isolated, draft-confirm-write-PR shape.

It writes to an existing home — it does not invent one​

The doc scaffolding already exists. This skill routes into it; it never creates new templates or directories.

Nature of the decisionHomeTemplateIndex
Technical / architectural (schema, infra, library, service boundary)docs/adrs/adr-NNN-<slug>.mddocs/templates/adr.mddocs/adrs/index.md
Product / business / process (pricing, vendor, support tier, team policy)docs/decisions/<slug>.mddocs/templates/decision.mddocs/decisions/index.md

The Decision template's Follow-up actions section and the ADR's Consequences + any explicit action items are what /breakdown consumes — they play the role the Implementation plan plays in a design doc.

No ClickUp ID in the filename. Decision records precede task creation, so unlike design docs and specs they are not named <slug>-<clickup-id>.md. ADRs are numbered adr-NNN-<slug>; decisions are date-prefixed YYYY-MM-<slug> (short kebab-case), per docs/templates/decision.md.

When to invoke​

Manual entry point: /decision [optional one-line topic].

Auto-invoke (after explicit user approval): when the developer pastes or describes a discussion that clearly reached decisions ("we decided to…", "סיכמנו ש…") and wants it kept. Offer:

"סוכמו פה החלטות. רוצה שאתעד אותן כ-decision record ב-bewith-docs?"

If they confirm, invoke. If "just a thought, nothing decided yet" → this is a proposal, not a decision record — offer /propose instead.

Decision record vs. proposal vs. design doc — fast triage​

TypeUse whenWhere
Proposal (/propose)An idea, not yet decided, needs triagedocs/proposals/
Decision record (/decision)A discussion reached decisions; tasks will flow from itdocs/adrs/ or docs/decisions/
Design doc (downstream)A single task is large enough to need how, after researchdocs/designs/

If unsure between ADR and decision log, ask one question (see step 3). If unsure whether anything was actually decided, default to proposal — it is the lighter, reversible choice.

Steps​

1. Confirm what you are about to record​

Restate, in two or three sentences: the topic, the decision(s) reached, and the participants. Get explicit confirmation. If the input is a raw summary (e.g. pasted from a meeting or another tool), normalize it to the target template — do not copy a foreign structure verbatim.

If the developer gave a long, research-heavy write-up, compress it: a decision record is the decisions + why + action items, not the analysis. The analysis belongs in a downstream design doc.

2. Collect the fields the template needs​

Ask only for what the discussion did not already give you:

  • Participants / deciders — who was in the discussion.
  • Context — the forcing function, in one or two sentences.
  • The decision(s) — one clear sentence each. A discussion may carry more than one; capture each.
  • Options considered — at least the chosen one vs. the main alternative, with the reason the alternative lost.
  • Action items — each as verb + object, with an owner and (if known) a due date. These become tasks.
  • Open questions — anything still unresolved (e.g. "which sprint" pending a lead's call).

No placeholder values (TBD, xxx, CU-pending). If a field is unknown, omit it and list it under open questions instead. All content English — translate a Hebrew discussion on the way in.

3. Route: ADR or decision log​

Ask one question if it is not obvious from the topic:

"טכני/ארכיטקטוני (→ ADR) או product/business/process (→ decision log)?"

Heuristic: if the decision changes code structure, data model, infrastructure, or a service contract → ADR. If it changes pricing, a vendor, a support tier, a team policy, or a product direction → decision log. A discussion that produced both a technical and a product decision is rare; if it happens, write one record per home and cross-link them.

4. Locate the bewith-docs checkout​

Follow the canonical resolution cascade in docs/methodology/session-safety.md — "Locating the bewith-docs checkout". Set BEWITH_DIR=<resolved path>. If no clone is found, stop and tell the developer.

5. Pre-flight safety checks​

# 5a. Derive the slug and (for ADR) the next number
SLUG="<kebab-case-title>"                      # decision log: docs/decisions/$(date +%Y-%m)-${SLUG}.md
# For an ADR, find the next NNN:
NEXT=$(ls "$BEWITH_DIR/docs/adrs/" | grep -oE 'adr-[0-9]+' | grep -oE '[0-9]+' | sort -n | tail -1)
NNN=$(printf "%03d" $(( ${NEXT:-0} + 1 )))     # ADR: docs/adrs/adr-${NNN}-${SLUG}.md
BRANCH="docs/decision-${SLUG}"                  # or docs/decision-adr-${NNN}-${SLUG}; "decision/" is NOT an allowed branch type

# 5b. Refuse if the file or branch already exists
DEST="$BEWITH_DIR/docs/decisions/$(date +%Y-%m)-${SLUG}.md"    # or the adr path
if [ -f "$DEST" ]; then echo "ERROR: $DEST already exists. Edit it or pick another slug." >&2; exit 1; fi
git -C "$BEWITH_DIR" fetch origin master --quiet
if git -C "$BEWITH_DIR" rev-parse --verify --quiet "refs/heads/${BRANCH}" >/dev/null; then echo "ERROR: branch ${BRANCH} exists locally." >&2; exit 1; fi
if git -C "$BEWITH_DIR" ls-remote --exit-code origin "${BRANCH}" >/dev/null 2>&1; then echo "ERROR: branch ${BRANCH} exists on remote — in-flight record." >&2; exit 1; fi

6. Create an isolated worktree​

Never operate on the developer's working tree — a concurrent session may be editing it. See docs/methodology/session-safety.md.

WORKTREE="$(mktemp -d -t bewith-decision.XXXXXXXX)"
git -C "$BEWITH_DIR" worktree add -b "${BRANCH}" "${WORKTREE}" origin/master --quiet
# Pre-commit validators import js-yaml etc.; a fresh worktree has no node_modules.
ln -s "$BEWITH_DIR/node_modules" "${WORKTREE}/node_modules"

Write the record into the worktree, not into $BEWITH_DIR.

7. Draft the record​

Copy the matching template and fill it from step 2. Keep the Docusaurus badge row from the template (it is MDX-safe as the proposals files demonstrate). The chosen template owns the section structure — do not add or rename sections.

  • ADR: status: proposed, fill deciders, Context, Decision, Rationale table, Consequences, Revisit trigger.
  • Decision: outcome: accepted (or as agreed), fill participants, What was decided, Context, Options considered, Decision rationale, Implications, Follow-up actions (one checkbox per action item, with owner + due where known).

8. Update the matching index​

Add a row to docs/decisions/index.md (Date · Title · Owner · Outcome) or docs/adrs/index.md, newest first. Do not auto-generate the index — it is hand-maintained.

9. Commit, push, and open a PR​

git -C "${WORKTREE}" add <record-path> <index-path>
git -C "${WORKTREE}" commit -m "$(cat <<'EOF'
decision: <short title>

<one-paragraph summary: what was decided and why, plus participants.>
EOF
)"
git -C "${WORKTREE}" push -u origin "${BRANCH}"
gh pr create --repo bewith-dev/bewith-docs --base master --head "${BRANCH}" \
  --title "decision: <short title>" --body "<summary + participants + action-item count>"

Surface the PR URL. Do not merge — a recorded decision is reviewable; let the participants confirm the record is faithful.

10. Clean up the worktree (always — use a trap)​

git -C "$BEWITH_DIR" worktree remove --force "${WORKTREE}"

11. Offer the breakdown​

Once the record exists, offer to generate tasks from its action items:

"תיעדתי. רוצה שאפצל את ה-action items ל-GitHub issues עכשיו? (/breakdown <record-path>)"

If yes, hand the record path to breakdown — it reads the Follow-up actions (decision log) or the explicit action items / Consequences (ADR) as the task source. Confirm the target repo there; do not assume it.

Failure modes​

  • No bewith-docs clone → stop, tell the developer. No fallbacks.
  • Branch / file already exists → stop, surface the clash, let them rename.
  • gh not authenticated → tell them to gh auth login; don't push without a PR follow-up.
  • Nothing was actually decided → this is a proposal, not a decision record. Redirect to /propose.

What this skill does NOT do​

  • It does NOT invent templates or directories — it writes into the existing docs/adrs/ and docs/decisions/ homes.
  • It does NOT open GitHub issues itself — that is /breakdown, offered as a follow-up.
  • It does NOT create a design doc — design docs are downstream, per task, after research.
  • It does NOT merge the PR — the record is reviewed by the participants.
  • It does NOT require a ClickUp ID — decision records precede task creation.

Cross-references​