@rasensio/aidlc-content 1.13.0 → 1.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rasensio/aidlc-content",
-  "version": "1.13.0",
+  "version": "1.13.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/resources/skills/roadmap-item/SKILL.md

@@ -15,15 +15,18 @@ or metadata. Ask about their idea. You produce the formatting.
 ## What to ask
 
 Ask for whatever is missing, a couple of questions at a time, and stop as soon as you can
-fill the four body sections. Three or four exchanges is plenty. A rough item is worth more
+fill the body sections. Three or four exchanges is plenty. A rough item is worth more
 than a polished one that never got written.
 
 You need:
 
 1. What problem this solves, and who has the problem.
 2. What would be true if it worked.
-3. Their name, for the record.
-4. Today's date, if you cannot determine it reliably.
+3. Whether it is meant to earn money, save money, or neither. Ask this plainly —
+   "would this make money, save money, or is it just something that needs doing?" —
+   and accept "neither" as a perfectly good answer.
+4. Their name, for the record.
+5. Today's date, if you cannot determine it reliably.
 
 Anything they do not know is allowed to stay unknown. Write `Not yet decided.` under a
 heading rather than inventing a plausible answer — a fabricated success metric is worse than
@@ -63,11 +66,13 @@ Rules for those fields:
 - Do not add any other field, and do not add a `status` field. Status is recorded by which
   folder the file sits in, not inside the file.
 
-Then the body, with these four headings and nothing else at this level:
+Then the body, with these five headings and nothing else at this level:
 
 ```
 # <the title again>
 
+## Executive Summary
+
 ## Problem
 
 ## Who it's for
@@ -81,6 +86,37 @@ Write plain prose under each. Short paragraphs or bullets, no tables. Two or thr
 per section is normal. `Out of scope` is where you record what they explicitly said they do
 *not* want — leave it as `Nothing stated yet.` if they said nothing.
 
+## The Executive Summary
+
+This is the section a busy decision-maker reads instead of the item. It comes first in the
+file and you write it **last**, once the other four sections exist — a summary written first
+is a guess.
+
+Use exactly these six labels, in this order, one or two sentences each:
+
+```
+- **What it is** — the change itself, in one sentence, in words a non-engineer would use.
+- **Who benefits** — the person who feels the pain today, named by role.
+- **Customer value** — what they can do afterwards that they cannot do now.
+- **Revenue** — Direct, Indirect, or None, then one sentence saying why.
+- **Cost and risk** — rough size (hours, days, weeks) and the main way it goes wrong.
+- **Recommendation** — Do now, Do later, or Don't do, plus the reason in one line.
+```
+
+Four rules make the difference between a summary worth reading and decoration:
+
+- **`None` is a real answer for revenue, and often the right one.** Plenty of necessary work
+  earns nothing directly. Writing `Indirect` for everything makes the field useless, which is
+  worse than leaving it blank, because it looks answered.
+- **Do not sell the idea.** You are summarising what someone told you, not pitching it. If
+  they described a small convenience, say so. An honest `Do later` is more useful to them
+  than an enthusiastic `Do now` that turns out wrong.
+- **Say `Not yet decided.` for any label you cannot fill.** Same rule as the rest of the
+  file: an admitted gap beats an invented number, because the next reader can tell the
+  difference.
+- **Keep it to six lines.** If the reasoning needs more room, that room is the `Problem`
+  section. A summary that runs to a page is not a summary.
+
 ## Where it goes
 
 Tell them to add the file to their project's roadmap inbox:

package/skills/04-roadmap.md

@@ -56,7 +56,33 @@ history:
 - **`depends_on`** names other items by `id`, so a dependency survives its target moving. Build order is derived from this graph when needed — there is no global `order` field, because concurrent capture from independent sessions cannot coordinate a sequence.
 - **`history`** is append-only and advisory. Append `{ status, at }` when you move an item. An absent or incomplete history is never an error, and current status always comes from the directory — never from the last history entry.
 
-Bodies are free-form. Items authored through the portable skill carry four headings — Problem, Who it's for, What success looks like, Out of scope — which is a useful shape, not a validated one.
+Bodies are otherwise free-form. Items authored through the portable skill carry four further headings — Problem, Who it's for, What success looks like, Out of scope — which is a useful shape, not a validated one.
+
+### Every Item Opens With an Executive Summary
+
+The first section of the body, before anything else, is `## Executive Summary` — six labelled lines, nothing more:
+
+```
+## Executive Summary
+
+- **What it is** — the change itself, in one sentence, in words a non-engineer would use.
+- **Who benefits** — the person who feels the pain today, named by role.
+- **Customer value** — what they can do afterwards that they cannot do now.
+- **Revenue** — Direct, Indirect, or None, then one sentence saying why.
+- **Cost and risk** — rough size (hours, days, weeks) and the main way it goes wrong.
+- **Recommendation** — Do now, Do later, or Don't do, plus the reason in one line.
+```
+
+This exists so a triage decision can be made from the top of the file. An item whose value cannot be stated in six lines is an item nobody can decide about, and it will sit in `inbox/` until somebody re-derives the case from scratch.
+
+Four rules keep it honest:
+
+- **`None` is a real answer for revenue, and often the correct one.** Lifecycle plumbing earns nothing directly. Writing `Indirect` for everything makes the field useless, which is worse than leaving it blank because it reads as answered. This is also the cheapest available check against the self-repair trap: a meta-feature that has to write `Revenue — None` and `Customer value — none, it observes the lifecycle` has declared itself.
+- **Write it last, from the rest of the body.** A summary drafted before the detail is a guess wearing a summary's clothes.
+- **`Not yet decided.` for any label you cannot fill.** An admitted gap beats an invented figure; the next reader can tell the difference.
+- **Six lines, no more.** Longer reasoning belongs in the sections below it.
+
+Older items may predate this section. Add it when you next touch such an item — derived from what the item already says, never from fresh speculation — rather than sweeping the whole directory.
 
 ## Capture
 
@@ -64,7 +90,8 @@ Bodies are free-form. Items authored through the portable skill carry four headi
 2. **Name the file.** `YYYYMMDD-<slug>.md` — today's date plus a short (2–4 word) slug.
 3. **Handle collisions.** If the filename already exists in *any* status directory, ask one question — extend the existing item or new item? On extend, append a dated `## Update (YYYY-MM-DD)` section to it where it is; on new, suffix the slug (`-2`). Never silently overwrite.
 4. **Write the file** into `inbox/`, with `source: human`, `promoted_to: null`, and one `history` entry dated today. Record `depends_on` only if the braindump itself names other items; never ask for dependencies. Do not interrogate the user for structure — capture friction kills inboxes; one braindump in, one file out.
-5. **Confirm and return.** Report the file path and return to whatever was happening.
+5. **Draft the executive summary from the braindump, do not extract it by interview.** You write those six lines; the user does not. Ask at most one question, and only when the braindump says nothing about who wants this or why — a good one is "would this make money, save money, or is it just something that needs doing?". Anything still unknown is `Not yet decided.`, which is the point of having the label.
+6. **Confirm and return.** Report the file path and the `Recommendation` line, then return to whatever was happening. Showing the recommendation lets the user correct a wrong read immediately, while the context is still in front of them.
 
 **Hard rule:** capture never reads or writes anything under `.aidlc/state/` — no claims, no phase files, no transitions log. Two sessions capturing simultaneously just produce two files; no locking exists or is needed. Do not auto-commit; staging is the user's.
 
@@ -74,12 +101,16 @@ If the user includes credentials, tokens, or secrets in a braindump, flag it and
 
 List each status directory, reading **only frontmatter and the containing directory** — never item bodies. Show each item's date, title, status, and dependencies. Group by status in lifecycle order and give a count per status. Flag `inbox/` items first: they are waiting on a decision only a human can make. Then flag `backlog/` items whose dependencies are all `done` — those are the natural next candidates. Offer to open, triage, promote, or drop.
 
+The frontmatter-only rule holds for browsing, which is a list and must stay cheap enough to run over the whole roadmap. **Triage** below is the one flow allowed into the body, and only as far as the executive summary.
+
 A filename appearing in two status directories is an error: report it rather than guessing which one is current.
 
 ## Triage
 
 Moving an `inbox/` item to `backlog/` means "we agree to do this". Moving it to `hold/` means "not now". Move the file and append the matching `history` entry. Triage is the one flow that exists purely because more than one person can submit work — do not skip it by promoting straight from `inbox/` unless the user says so.
 
+Triage is the one flow that reads into the body, and it reads **the executive summary and nothing else**. Six labelled lines per item is what makes triaging a full inbox in one sitting possible; opening whole items is what makes triage something nobody ever gets round to. Show the summary, say which way you would go and why, and let the human decide. If an item has no executive summary, write one from what the item says before asking for a decision — a decision made without one is a decision made twice.
+
 ## Promote
 
 Promotion is where the roadmap meets the lifecycle: