| name | decision-first |
| description | Makes an architectural / project / scope decision using a 5-part model
INSTEAD of asking the user. Structure: ๐ฏ Decision / Why / ๐ก Security /
๐ Scalability / Alternatives / Plain-language analogy.
1 question = 1 atomic artifact.
Use when: the agent is about to ask an architectural / scope question;
"/decision-first", "decide it yourself", "apply the decision model"
|
Decision-First Protocol
Makes a decision on behalf of the user via a 5-section model with full reasoning and alternatives. Invoked whenever the agent is about to ask an architectural / project / scope question โ instead of asking, the skill is called.
Core idea: the user prefers autonomous decisions with transparent reasoning over back-and-forth Q&A. A decision can be contested post-hoc (round 2) โ cheaper than a synchronous pause-and-ask.
When to call: exists 2+ reasonable alternatives and a justified selection is required. If one option is obviously correct โ do not call, just act.
Input
An ambiguous architectural, scope, or design question the agent is about to ask the user.
Output
decision-{NN}.md capturing the choice via a 5-part model (๐ฏ Decision / Why / ๐ก Safety / ๐ Scalability / Alternatives / In plain language).
Hands off to
Returns control to the calling skill (typically arch-first, plan-first, or library-first).
Step 0 โ Task context
Ensure {log_dir} and {slug} are known. Otherwise resolve from the latest task log folder.
Step 1 โ Identify decision(s)
Auto-mode โ pick the last unresolved question from the current conversation. If related questions cluster (e.g. "flatten + format" = 2 decisions) โ handle all in one invocation, one artifact per decision.
Manual mode (/decision-first) โ either process the questions the user described, or ask "which questions?".
Cutoff: obvious choice โ skip the skill, just act.
Step 2 โ Apply the 5-section model
Per decision:
# D{N} โ {short title}
๐ฏ **Decision:** {chosen option in one sentence}
**Why this option:**
- {specific reason 1}
- {specific reason 2}
**๐ก Security:** {security analysis. If N/A โ explicit `not applicable`}
**๐ Scalability:** {scaling impact. If N/A โ explicit `not applicable`}
| Alternative | Why rejected |
|---|---|
| {option 1} | {concrete drawback} |
| {option 2} | {concrete drawback} |
**Plain-language analogy:** {real-world analogy without technical jargon}
Rules:
- ๐ฏ Decision โ one sentence, no "possibly X"
- Why โ 2 to 5 concrete reasons
- ๐ก Security + ๐ Scalability โ always present (even if
not applicable with rationale)
- At least 2 real alternatives (no straw men)
- Analogy โ from real life (warehouse / shop / kitchen)
Step 3 โ Numbering
Per-task auto-numbering scoped to {log_dir}:
NEXT_NN=$(( $(ls "{log_dir}"/decision-*.md 2>/dev/null | wc -l) + 1 ))
Format decision-{NN}.md (zero-padded). Retry โ decision-{NN}.R2.md.
Step 4 โ Write and register
Each decision = one file {log_dir}/decision-{NN}.md. Add a row to task.md ## Task files section + a link block at the end.
Register in task_artifacts (one row per decision):
sqlite3 {routing_db} \
"INSERT INTO task_artifacts
(task_id, block_num, round_num, artifact_type, file_name, file_path, created_by, created_at)
VALUES ('{slug}', {block_num or NULL}, 1, 'decision', 'decision-{NN}.md',
'{log_dir}/decision-{NN}.md', 'decision-first', '{date}');"
Step 5 โ Output summary
Group decisions inline in chat:
โ
Decision-first โ N decisions taken:
[D{NN}] ๐ฏ {chosen} โ {1-line reasoning}
[D{NN+1}] ๐ฏ {chosen} โ {1-line reasoning}
After output โ continue working. Do not wait for approval (user objects โ "rewrite D{NN}" triggers round 2).
Principles
- Do not ask โ call the skill instead of asking the user
- All 5 sections mandatory โ even
not applicable must be explicit
- Real alternatives only โ no straw men
- Analogy mandatory โ makes the decision accessible to non-technical stakeholders
- 1 question = 1 artifact โ for analytics and typing
- Flag unknowns โ insufficient data โ mark as
โ ๏ธ requires validation
Anti-patterns
โ Asking a question instead of the skill
2+ alternatives + no clear winner โ call the skill. Do not ask.
โ Skipping Security or Scalability
UI/cosmetic doesn't excuse silence. Write not applicable with a reason.
โ Straw-man alternatives
Alternatives must be viable choices in the same value system.
โ Silent choice under insufficient data
Explicitly flag โ ๏ธ requires validation โ do not hide the uncertainty.
โ Bundling multiple decisions in one file
1 question = 1 file = 1 row in task_artifacts. Group visually in chat only.
โ Inlining instead of Skill()
Always via the Skill tool โ otherwise version drift + no artifact registration.
Example โ reference decision (public form)
# D1 โ `producer_id` in draft: denormalize or JOIN?
๐ฏ **Decision:** denormalize โ copy `producer_id` from source into draft at INSERT.
**Why this option:**
- Analytics queries filter by producer often. JOIN on millions of rows is slow.
- INTEGER (4 bytes) โ cheap in storage.
- Source is immutable after processing โ single source of truth preserved.
**๐ก Security:** validated by the catalog FK trigger at INSERT โ no forgery. Deactivating the producer blocks new INSERTs, keeps old audit trail.
**๐ Scalability:** 1M rows โ SELECT without JOIN = O(log n) with an index. With JOIN โ double scan. On 10M rows โ seconds vs milliseconds.
| Alternative | Why rejected |
|---|---|
| JOIN on every analytics | Degrades on large volumes |
| Materialized view | SQLite has no MV. VIEW = same JOIN under the hood |
| Periodic refresh job | Sync complexity. Denormalization at INSERT is simpler |
**Plain-language analogy:** imagine an archive of invoices. Storing only supplier id โ building a report by supplier is slow (JOIN with registry). Storing a small copy of the supplier label right next to the invoice โ report is instant. Registry updates don't affect the archive because the archive is history, not the present.
Related skills
- plan-first โ plans execution steps (after decisions are made)
- note-first โ saves a free-form note (after user request)
- arch-first โ multi-block architectural tasks (invokes decision-first at forks)
