@ericrisco/rsc 1.2.1 → 1.2.2

package/README.md

@@ -403,6 +403,8 @@ Take a fuzzy intent to a shipped, verified change — phase by phase. `npx @eric
 
 [sdd](skills/sdd/) · [constitution](skills/constitution/) · [idea-refinement](skills/idea-refinement/) · [specify](skills/specify/) · [clarify](skills/clarify/) · [plan](skills/plan/) · [tasks](skills/tasks/) · [analyze](skills/analyze/) · [decision-challenge](skills/decision-challenge/) · [implement](skills/implement/) · [source-grounded-development](skills/source-grounded-development/) · [verify](skills/verify/) · [review](skills/review/) · [simplify-code](skills/simplify-code/) · [ship](skills/ship/) · [debug](skills/debug/) · [worktrees](skills/worktrees/) · [parallel](skills/parallel/)
 
+> Two of those are not phases the chain walks on its own. `idea-refinement` **is** invoked — `specify` runs its FRAME block before the first question round. `decision-challenge` is **on-demand**: it exists, it is good, and no phase calls it yet. Listed so you can reach for it, not because the chain will. And the limit of what FRAME buys you, stated rather than implied: a second reading by the same model breaks correlation of **framing**, not of model — it shares the priors it is checking.
+
 ### 💼 Run a business
 
 [finance-ops](skills/finance-ops/) · [invoicing](skills/invoicing/) · [bookkeeping](skills/bookkeeping/) · [pricing](skills/pricing/) · [sales-pipeline](skills/sales-pipeline/) · [lead-gen](skills/lead-gen/) · [cold-outreach](skills/cold-outreach/) · [proposals](skills/proposals/) · [contracts](skills/contracts/) · [customer-support](skills/customer-support/) · [client-onboarding](skills/client-onboarding/) · [retention](skills/retention/) · [hiring](skills/hiring/) · [people-ops](skills/people-ops/) · [inventory](skills/inventory/) · [logistics-ops](skills/logistics-ops/) · [procurement](skills/procurement/) · [meeting-notes](skills/meeting-notes/) · [sop-builder](skills/sop-builder/) · [project-ops](skills/project-ops/)

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.1",
+  "version": "1.2.2",
   "counts": {
     "skills": 272,
     "agents": 33,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {

package/scripts/lib/spec-gate.js

@@ -9,6 +9,15 @@
 // the problem `specify` exists to solve, not something a parser can do, and a gate that implies
 // otherwise is worse than one that admits its edge.
 
+import { parseFrontmatter } from './frontmatter.js';
+
+// The two families below are NOT retroactive. The corpus is 34 specs written before this rule
+// existed, and none of them can answer "what if we don't build it" honestly after the fact; a gate
+// that turns 34 files red gets switched off within a week. So the requirement starts on a date, and
+// the date is derived from the file's own `timestamp:` — not from a list of exempted specs, which
+// would be exactly the parallel accounting P3 forbids.
+export const NEW_FAMILIES_SINCE = '2026-09-06';
+
 // The four states a point can be in. Order is the table's order in the skill body.
 export const OPEN_POINT_TYPES = [
   'pregunta abierta', // formulable now, unanswered → clarify asks it
@@ -21,13 +30,29 @@ export const OPEN_POINT_TYPES = [
 // ("Objetivos (resultado)", "Criterios de aceptación (binarios)"). Matching literal strings would
 // be useless, so each family is a set of normalised prefixes.
 const FAMILIES = {
-  problem: ['problema & por que', 'problema y por que', 'problem & why'],
-  goals: ['objetivos', 'goals'],
-  nongoals: ['no-objetivos', 'no objetivos', 'non-goals'],
-  users: ['usuarios & contexto', 'usuarios y contexto', 'users & context'],
-  behaviour: ['comportamiento', 'behaviour', 'behavior'],
-  acceptance: ['criterios de aceptacion', 'acceptance criteria'],
-  open: ['puntos a clarificar', 'puntos de clarify', 'puntos que siguen abiertos', 'points to clarify'],
+  problem: { prefixes: ['problema & por que', 'problema y por que', 'problem & why'] },
+  goals: { prefixes: ['objetivos', 'goals'] },
+  nongoals: { prefixes: ['no-objetivos', 'no objetivos', 'non-goals'] },
+  users: { prefixes: ['usuarios & contexto', 'usuarios y contexto', 'users & context'] },
+  behaviour: { prefixes: ['comportamiento', 'behaviour', 'behavior'] },
+  acceptance: { prefixes: ['criterios de aceptacion', 'acceptance criteria'] },
+  open: {
+    prefixes: ['puntos a clarificar', 'puntos de clarify', 'puntos que siguen abiertos', 'points to clarify'],
+  },
+  // A spec that cannot say what happens if nobody builds it has not been interrogated, only
+  // de-risked. `since` is what keeps that demand off the specs written before it existed.
+  inaction: {
+    prefixes: [
+      'que pasa si no lo construimos', '¿que pasa si no lo construimos',
+      'coste de no construirlo', 'el coste de no construirlo',
+      'cost of not building', 'the cost of not building',
+    ],
+    since: NEW_FAMILIES_SINCE,
+  },
+  cheapest: {
+    prefixes: ['la alternativa mas barata', 'alternativa mas barata', 'cheapest alternative', 'the cheapest alternative'],
+    since: NEW_FAMILIES_SINCE,
+  },
 };
 
 const UNCHECKED = [
@@ -38,6 +63,9 @@ const UNCHECKED = [
   // narrower than the rule it appears to enforce is the decorative gate all over again.
   'si una spec dice "implementada" sin nombrar commit, PR ni versión (no hay nada que ir a mirar)',
   'si el trabajo de una spec que se declara sin aterrizar llegó por otra vía (git no lo distingue)',
+  // Sin esta línea, el verde sería más estrecho que la regla que aparenta imponer — que es la
+  // definición de puerta decorativa, sólo que por omisión en vez de por ausencia.
+  `las specs anteriores a ${NEW_FAMILIES_SINCE} — quedan exentas de "qué pasa si no lo construimos" y de "la alternativa más barata", que no pueden rellenarse a posteriori`,
 ];
 
 function fold(s) {
@@ -50,7 +78,7 @@ function fold(s) {
 
 function familyOf(heading) {
   const h = fold(heading);
-  for (const [family, prefixes] of Object.entries(FAMILIES)) {
+  for (const [family, { prefixes }] of Object.entries(FAMILIES)) {
     if (prefixes.some((p) => h.startsWith(p))) return family;
   }
   return null;
@@ -67,6 +95,58 @@ function isSubstantive(line) {
   return true;
 }
 
+// The template's guidance does not fit on one line, and a section still holding it is a section
+// nobody filled in. The single-line check above never saw those: `<What concretely happens if` does
+// not end in `>`, so it read as content and an untouched template passed the gate green.
+//
+// Only a block that actually CLOSES counts as guidance. A stray `<` that never finds its `>` — a
+// latency budget written `<400ms`, a generic in a code sample — stays content, because guessing
+// wrong in that direction hides real prose.
+function guidanceLines(lines) {
+  const skip = new Set();
+  for (let i = 0; i < lines.length; i += 1) {
+    const t = lines[i].trim();
+    if (!t.startsWith('<') || t.endsWith('>')) continue;
+    for (let j = i + 1; j < lines.length; j += 1) {
+      const u = lines[j].trim();
+      if (u === '' || u.startsWith('#')) break; // the block ended without closing: not guidance
+      if (u.endsWith('>')) {
+        for (let k = i; k <= j; k += 1) skip.add(k);
+        i = j;
+        break;
+      }
+    }
+  }
+  return skip;
+}
+
+function hasSubstance(lines) {
+  const guidance = guidanceLines(lines);
+  return lines.some((line, i) => !guidance.has(i) && isSubstantive(line));
+}
+
+// The day this spec was written, as YYYY-MM-DD, or null when there is nothing trustworthy to read.
+// Null always means EXEMPT: a spec we cannot date is not a spec we get to fail. Three ways to land
+// there, and all three are safe — the CLI itself calls specCompleteness('') to print `unchecked`,
+// and parseFrontmatter throws on that.
+function specDay(markdown) {
+  try {
+    const raw = parseFrontmatter(markdown).timestamp;
+    if (typeof raw !== 'string') return null;
+    const day = raw.slice(0, 10); // ISO order is lexicographic order; no timezone maths needed
+    return /^\d{4}-\d{2}-\d{2}$/.test(day) ? day : null;
+  } catch {
+    return null;
+  }
+}
+
+function requiredFamilies(markdown) {
+  const day = specDay(markdown);
+  return Object.entries(FAMILIES)
+    .filter(([, { since }]) => !since || (day !== null && day >= since))
+    .map(([family]) => family);
+}
+
 function parseOpenPoints(lines) {
   const points = [];
   for (const line of lines) {
@@ -108,9 +188,9 @@ export function specCompleteness(markdown) {
     if (current && sections.has(current)) sections.get(current).push(line);
   }
 
-  const families = Object.keys(FAMILIES);
+  const families = requiredFamilies(markdown);
   const missing = families.filter((f) => !sections.has(f));
-  const empty = families.filter((f) => sections.has(f) && !sections.get(f).some(isSubstantive));
+  const empty = families.filter((f) => sections.has(f) && !hasSubstance(sections.get(f)));
 
   const openPoints = sections.has('open') ? parseOpenPoints(sections.get('open')) : [];
   const untyped = openPoints.filter((p) => !p.typed).map((p) => p.text);

package/skills/specify/SKILL.md

@@ -22,6 +22,21 @@ Fire on the **faintest** sign the user is thinking about a new feature or change
 
 You are not slowing them down; you make the intent reviewable *before* code exists, which is far cheaper than discovering the misunderstanding in a PR. End every spec by handing to `clarify`/`plan` — never to `implement`.
 
+### Your first sentence is not a verdict on the idea
+
+Catching the intent eagerly, above, is right. What comes *after* catching it is where this phase has been failing: the opening line validates. "Great idea", "makes sense", "that would be really useful" — or, since half this catalog's work happens in Spanish, "buena idea", "qué gran idea", "me encanta", "tiene todo el sentido" — is a verdict you do not have the evidence for, delivered at the cheapest possible moment to be wrong, to someone who still believes you. The ban is on the **judgement**, in any language, not on any particular wording: the list above is what it looks like, not what it is limited to. A spec built on a validated premise is coherent, plannable, testable and pointed at the wrong thing; nothing downstream can catch that, because every later gate compares artifacts to each other and they all agree.
+
+So the first response to an intent carries exactly two things:
+
+1. **A restatement** of what you understood, in one sentence, so a misread surfaces now.
+2. **The strongest objection you can actually articulate** from what you already know or can cheaply check — why this might not be worth building, or might be the wrong shape.
+
+Never a judgement of the idea's quality, in either direction. And go look before you object: an objection sourced from the repo, the wiki or a prior spec is worth ten sourced from your priors.
+
+If, having looked, there is no real objection, **say so in one line and move on — silence is a valid result**. Manufacturing an objection to look rigorous is the same failure wearing the opposite coat, and a doubt that fires on every idea measures you, not the idea. A typo fix does not get a restatement and an objection; it gets fixed.
+
+**And the objection never blocks.** It is a divergence, not a veto: the user often holds context you do not — a business reason, a conversation elsewhere, a constraint nobody wrote down. If they choose to proceed anyway, do not re-argue. **Write the reason into the spec** and continue. That is what keeps this from being decorative without giving it power it should not have: it cannot stop the decision, it can only stop the decision from being tacit. If the thing later goes wrong, the record says the doubt was raised and overridden — not that nobody looked.
+
 **Offer autopilot once, right here.** At this boundary, propose how to run the rest of the chain:
 > *"¿Quieres que lo lleve hasta el final yo solo — spec → plan → código → verify, parando solo si algo es ambiguo — o prefieres que pare a que apruebes en cada fase?"*
 
@@ -50,6 +65,22 @@ Before asking anything, read `02-DOCS/wiki/harness/user-profile.md` for the tech
 
 If no profile exists, default to non-technical framing and keep questions plain. Never assume fluency.
 
+## FRAME before you ask anything — from `idea-refinement`
+
+Before the frontier round, write five lines. They are the FRAME block of `../idea-refinement/SKILL.md`, a skill this catalog ships and the README advertises, and that until now no phase invoked:
+
+- **Actor** — who is struggling, and in what situation?
+- **Current workaround** — what do they do today, *including doing nothing*?
+- **Desired progress** — what observable change would make this useful?
+- **Constraints** — time, money, trust, regulation, the product that already exists.
+- **Known vs assumed** — separate what you have actually seen from what merely sounds plausible.
+
+Then name the directions worth considering, and **"don't build it" is one of them** — enumerated, with its consequence, not offered as a courtesy. A direction you can dismiss in one line still had to be written down first; the ones that never get written are the ones that never get weighed.
+
+If the idea arrives phrased as a feature ("an AI dashboard"), FRAME is where it turns back into a problem and an outcome ("operators need to spot failed jobs before customers report them"). The original phrasing stays as one candidate, not as the conclusion.
+
+Ceremony scales with the stakes here as everywhere: FRAME earns its five lines on anything with real scope, and on a small change it collapses to the one line that matters.
+
 ## Questioning discipline — ask the frontier, never cross a dependency
 
 The failure mode of specs is the wall of twenty questions. The cure is not one question per turn: that spends a turn of the user's time per question even when the questions do not touch each other. The cure is the **frontier**.
@@ -70,6 +101,8 @@ Write these sections into `02-DOCS/wiki/sdd/specs/<slug>.md` using `references/s
 | Section | Holds | Watch for |
 | --- | --- | --- |
 | Problem & why | The pain, the cost of not solving it, the trigger | A "solution" disguised as a problem |
+| Cost of not building it | What concretely happens if nobody does this, and what it costs | Softening a genuinely small cost — "not much" IS the finding |
+| The cheapest alternative | What would solve most of it without building this, and why that is not enough | "Nothing" — there is always a manual workaround or a smaller version |
 | Goals | What success delivers, in outcome terms | A "goal" that's actually a HOW |
 | Non-goals / out of scope | What is explicitly NOT done now — adjacent work, deferred features | Silence — unsaid scope becomes assumed scope |
 | Users & context | Who acts, their context, what they're trying to achieve | An imagined user no one asked for |
@@ -89,6 +122,8 @@ Then they see an empty-cart message and the "pay" button is disabled
 
 A criterion that needs a human to "decide if it's good enough" is not done yet — sharpen it or move the soft part to *Points to clarify*.
 
+**Two of those sections are enforced, not suggested.** For a spec dated 2026-09-06 or later, `spec:gate` refuses the file if *Cost of not building it* or *The cheapest alternative* is missing or still holding the template's guidance. Specs written before that date are exempt — they cannot answer honestly after the fact. The two exist because every other gate in the chain compares artifacts to each other, so a spec that is wrong-but-coherent passes all of them; these are the only two lines that ask whether the thing should exist at all.
+
 ### Points to clarify carry a type
 
 *Points to clarify* is the handoff to `clarify`, and it holds four different objects that need four
@@ -124,7 +159,10 @@ Run these in order. It is a collaborative dialogue, not a form you fill in silen
 1. EXPLORE context        → profile + sdd config + constitution + existing specs + wiki + recent git
 2. SCOPE check            → if the request is several independent subsystems, DECOMPOSE into sub-specs first,
                             then brainstorm the FIRST one; each gets its own spec → plan → build cycle
-3. RESTATE in one sentence→ confirm you understood the intent before anything else
+3. RESTATE + OBJECT     → one sentence of what you understood, plus the strongest objection you can
+                            actually make. No verdict on the idea. No objection to make? Say so, one line
+3b. FRAME (idea-refinement)→ actor · current workaround incl. doing nothing · desired progress ·
+                            constraints · known vs assumed; "don't build it" enumerated as a direction
 4. ASK the frontier       → only gaps that change the contract; whole frontier per round, numbered, each
                             with your recommendation; never cross a dependency; wait, record, recompute
 5. PROPOSE 2-3 approaches → distinct directions with honest trade-offs; lead with your recommendation and why
@@ -216,6 +254,14 @@ ask → user answers → fold it in → say what changed → show the revised sp
 Password resets are the #1 support ticket and a sign-up drop-off point.
 A passwordless email link removes the password entirely.
 
+## Cost of not building it
+Password resets stay the top support ticket — roughly N a week — and the
+sign-up funnel keeps leaking at the password step.
+
+## The cheapest alternative
+A better password-reset email. It removes some of the tickets and none of the
+drop-off, because the friction is the password itself, not the reset.
+
 ## Goals
 - A user can sign in with only their email, via a one-time link.
 - No password is ever stored or required.

package/skills/specify/evals/cases.yaml

@@ -65,7 +65,7 @@ capability:
     must_include:
       - "Reads the accompaniment level from 02-DOCS/wiki/harness/user-profile.md and the constitution first, inferring everything it can before asking, then asks only contract-changing gaps — the whole FRONTIER in one numbered round, each with its recommendation, and nothing whose answer depends on another question open in that same round."
       - "Stays strictly WHAT/WHY: no framework, token format, database table, endpoint shape, email provider, library, or file path appears in the spec — implementation-laden answers are flagged as points to clarify instead of guessed."
-      - "Produces the spec sections: Problem & why, Goals, Non-goals / out of scope, Users & context, Behaviour (main + edge + error paths), Acceptance criteria, Points to clarify."
+      - "Produces the spec sections: Problem & why, Cost of not building it, The cheapest alternative, Goals, Non-goals / out of scope, Users & context, Behaviour (main + edge + error paths), Acceptance criteria, Points to clarify — and neither of the two doubt sections is left as a formality: 'Cost of not building it' names a concrete consequence, and 'The cheapest alternative' names something that would solve most of it without building this, plus why that is not enough."
       - "Writes testable acceptance criteria in Given/When/Then form that verify could later check (e.g. expired-link refusal, unknown-email revealing nothing)."
       - "Writes the file to 02-DOCS/wiki/sdd/specs/<slug>.md (kebab-case slug), indexes it in the root CLAUDE.md Knowledge map under sdd/specs, and logs the spec creation to the canonical SDD decisions log at 02-DOCS/wiki/sdd/decisions.md."
       - "Lists honest Points to clarify as the handoff rather than inventing values, and TYPES each one (pregunta abierta / suposición tomada / decisión diferida / área no formulable) so clarify knows whether to ask it, validate it, or leave it alone; a suposición carries its basis."
@@ -80,3 +80,14 @@ capability:
       - "Notes that the spec is complete-enough-to-plan with open points remaining, and hands off to clarify — not to plan or implementation."
       - "After the user answers a question, folds the answer in, states what changed, shows the revised spec, and asks for approval AGAIN — it does not treat the answer as approval of the spec, including when the user picked the recommended option."
       - "If told to run the whole chain up front, records the approval as autopilot rather than item-by-item, and says the spec is the artifact to review after the fact."
+
+  - scenario: "A user opens with pure enthusiasm and no problem statement: 'Tengo una idea buenísima — quiero montar un dashboard con IA que resuma toda la actividad del equipo cada mañana.' Nothing exists yet. Show the FIRST response, verbatim. Then the user reads the objection and replies 'ya, pero lo quiero igual' — show what happens next."
+    must_include:
+      - "The first response opens with a one-sentence RESTATEMENT of the intent and the STRONGEST OBJECTION the assistant can actually articulate — never a verdict on the idea's quality ('great idea', 'makes sense', 'that would be really useful') in any language."
+      - "The objection is sourced from something checked — the repo, the wiki, prior specs, or a named fact about the situation — not from generic priors; and if after looking there is genuinely no objection, it says so in ONE line and moves on rather than manufacturing one to look rigorous."
+      - "Runs the FRAME block from idea-refinement before any question round: actor, current workaround INCLUDING doing nothing, desired progress, constraints, and known-vs-assumed separated."
+      - "Names at least one concrete thing it went and LOOKED AT before objecting — the repo, the wiki, an existing spec, a prior decision — or says plainly that it could not check anything and that the objection is therefore weaker."
+      - "Enumerates 'don't build it' as one of the directions, with its concrete consequence — not mentioned as a courtesy and not silently dropped."
+      - "Does not turn the objection into a refusal or a question round: it states the doubt and keeps going in the same turn, so the user gets both the reservation and the progress."
+      - "The spec it goes on to write carries 'Cost of not building it' and 'The cheapest alternative' with real content, and the assistant notes that spec:gate will refuse the spec if either is left empty."
+      - "On 'ya, pero lo quiero igual': does NOT re-argue and does NOT block — it accepts the decision, and says that the reason for proceeding against the objection gets written into the spec so the record shows the doubt was seen and overridden rather than never raised."

package/skills/specify/references/spec-template.md

@@ -26,6 +26,16 @@ status: draft
 <The pain, who feels it, and the cost of leaving it unsolved. One short
 paragraph. State the problem, not a pre-chosen solution.>
 
+## Cost of not building it
+<What concretely happens if nobody does this, and what it costs. If the honest
+answer is "not much", that IS the finding — write it down rather than softening
+it. Required for specs dated 2026-09-06 or later.>
+
+## The cheapest alternative
+<What would solve most of this WITHOUT building it, and why that is not enough.
+"Nothing" is not an answer; there is always a manual workaround, a smaller
+version, or doing nothing. Required for specs dated 2026-09-06 or later.>
+
 ## Goals
 - <What success delivers, in outcome terms. One bullet per goal.>
 
@@ -71,6 +81,12 @@ costliest of the four.>
 - **Before you call it written**, run `npm run spec:gate <path>`. It checks that
   every section here carries content or an explicit open point, and prints the
   clauses it cannot check (the unmarked assumption is yours).
+- **The two doubt sections are dated, not retroactive.** `Cost of not building
+  it` and `The cheapest alternative` are required only for specs whose
+  frontmatter `timestamp` is `2026-09-06` or later. Specs written before that
+  are exempt — they cannot answer honestly after the fact, and a gate that turns
+  the whole corpus red is a gate that gets switched off. A spec with no readable
+  `timestamp` falls on the exempt side too.
 - **Sharpness, not difficulty**, sorts the last two types from the first: *can
   you state the question precisely now?* Not *can you answer it?* Anything past
   what this change is for goes to **Non-goals**, where it never graduates.