| name | session-to-proposal |
| description | Drafts a concise decision proposal in the form "we should do X because Y" from the current chat or session topic. Use when the user asks to turn something into a proposal ("let's turn this into a proposal"), wants a proposal drafted from recent discussion, or when summarizing an agreed direction for a feature, refactor, code standard, or process change. May also be offered proactively when a clear decision statement would help — especially after discussion. |
Session → proposal
Goal
Turn what was just discussed into a proposal: a concrete X (action) and
Y (reasoning grounded in shared context). Prefer speed and clarity over
polish.
Triggers
- "Turn this into a proposal," "write this up as a proposal," "proposal for what
we discussed."
- The thread has converged on a direction but it's still implicit — a short
proposal makes the next step obvious.
If the ask is vague and the topic is unclear from context, ask one or
two focused questions before drafting.
Default shape (short first)
Start small. Shorter is better unless complexity forces more.
- Proposal — One sentence: what we should do (X). Often starts with
"Proposal:" or "Let's …".
- Reasoning — 2–5 bullets that justify X (Y). Each ties to
something the reader already shares — prior decisions, docs, goals,
constraints — or flags what's new.
Everything after Reasoning is optional. Add further sections only when the
stakes warrant it. Do not pad.
Optional sections (after reasoning)
- Specifics — More detail on the likely implementation path, to confirm
alignment on direction (not to specify every detail).
- Supporting artifact — A link to a spec, doc section, PR, or sketch when X
or Y has many moving parts.
- Assumptions / new concepts — Separate net-new ideas from shared grounding.
- Alternatives considered — Including "do nothing" / "defer," if the
discussion actually weighed options.
- Risks / mitigations — When failure modes matter.
- Open questions — When Y is partly ungrounded; say what would resolve it.
- Decision ask — What you need from the reader (approve, choose A vs B), if
not obvious.
Where it lands
A proposal is the lightweight front end of katalyst's decision flow. When it's
accepted, graduate it: open questions become GitHub issues (or live in the
in-flight spec), and the locked rationale folds into the relevant
docs/deep-dives/ page — there is no central decisions log. See
docs/contributing/how-we-plan.md.
Principles
- X can be any follow-up: build, research, rename, adopt a standard, stop
doing something.
- Y should lean on shared docs, decisions, and priorities; introduce new
assumptions only when necessary and call them out.
- Substance (action + reason) matters more than formatting.
Examples (short form)
Example 1 — naming
Proposal: name the conformance verb `check`, not `validate`.
- The engine's primitive is already a `Check` (`internal/checks/`, `CheckType`) —
`check` runs the checks; `validate` would be a second word for the same idea.
- It covers the non-schema rules too (filename, headings), which "validate"
(schema-conformance) doesn't connote.
Example 2 — config structure
Proposal: replace the anonymous `rules:` list in katalyst.yaml with named
`collections:`.
- Addressing (`notes/dune`) needs named collections to resolve against; the CLI
spec depends on it (`product/specs/cli-spec.md`).
- It makes `collection` a first-class noun, matching the domain model
(`docs/reference/glossary.md`) instead of an implicit glob.
Workflow
- Infer X and the strongest Y bullets from the session.
- If X is ambiguous or Y would be mostly hand-wavy, ask brief
clarifying questions.
- Emit the Proposal line + Reasoning bullets first.
- Add optional sections only if they reduce confusion or record something the
session already established.
