create-pmos 0.38.4 → 0.38.6

package/payload/scripts/workflow-sweep.js

@@ -76,6 +76,11 @@ const CLASSES = {
   'missing-record': { severity: DEFECT, repairable: true, why: 'work merged with no record is invisible to every board and to the gate' },
   'unresolvable-anchor': { severity: DEFECT, repairable: false, why: 'the anchor names something the OKR documents do not declare (D59)' },
   'unverifiable-delivery': { severity: DEFECT, repairable: false, why: 'delivered_by names a commit the trunk cannot reach, or one that changes no build path (R-2b)' },
+  'unpointed-artifact': { severity: DEFECT, repairable: true, why: 'a document names this initiative and no path key in the record points at it, so the ladder reads the step as open over finished work (D77)' },
+  'lane-outside-profile': { severity: DEFECT, repairable: false, why: 'the record names a lane its repository profile does not offer, so the engine applies a different lane than the one written (D68, D77)' },
+  'acceptance-not-counted': { severity: DEFECT, repairable: false, why: 'an acceptances.jsonl row names an initiative and the ladder does not count it, so the ladder shows the gate open over a row that looks like an approval (D12)' },
+  'done-without-basis': { severity: DEFECT, repairable: false, why: 'a step reads done and names no file, ledger or commit history, so the pane has nothing to open (D77)' },
+  'status-claims-ahead': { severity: OWED, repairable: false, why: 'the record\'s status says accepted or complete while the ladder shows the acceptance step open' },
   'delivered-unlogged': { severity: OWED, repairable: false, why: 'the trunk attributes work to this initiative and no run was ever logged (AGENTS.md step 7)' },
   'delivered-unreviewed': { severity: OWED, repairable: false, why: 'delivered against a rubric with no Review-Gate verdict recorded — a skipped gate is recorded as skipped, never left absent' },
   'delivered-unaccepted': { severity: OWED, repairable: false, why: 'delivered with no acceptance row — the D12 gate is open' },
@@ -169,6 +174,43 @@ function candidatesFor(root, L, key, id) {
   return [...new Set(out)];
 }
 
+/*
+ * D77 — documents that name an initiative. The engine reads only the paths a record points at and
+ * never searches, so a finished PRD that no record points at leaves its step open. This is the search
+ * the engine does not do. It reads Markdown under the conventional document folders, skips the
+ * folders that hold control records, ledgers, rubrics and explainers, and matches on the file's
+ * `initiative_id` (frontmatter or a leading bullet) or on a name that starts with the id.
+ */
+const DOC_ROOTS = ['planning', 'docs', 'doc', 'prd', 'prds', 'briefs', 'specs', 'strategy', 'plans', 'reports', 'decisions', 'requirements', 'product'];
+const DOC_SKIP = new Set(['node_modules', '.git', 'initiatives', 'runs', 'state', 'explainers', 'evals', 'okf']);
+function buildDocIndex(root) {
+  const out = [];
+  const walk = (dirRel, depth) => {
+    if (depth > 4 || out.length > 5000) return;
+    let ents;
+    try { ents = fs.readdirSync(path.join(root, dirRel), { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      const rel = dirRel ? `${dirRel}/${e.name}` : e.name;
+      if (e.isDirectory()) { if (!DOC_SKIP.has(e.name)) walk(rel, depth + 1); continue; }
+      if (!/\.md$/i.test(e.name) || /^(index|log)\.md$/i.test(e.name)) continue;
+      let head = '';
+      try {
+        const fd = fs.openSync(path.join(root, rel), 'r');
+        const buf = Buffer.alloc(3000); const n = fs.readSync(fd, buf, 0, 3000, 0); fs.closeSync(fd);
+        head = buf.slice(0, n).toString('utf8');
+      } catch { continue; }
+      const m = head.match(/^[-\s]*initiative_id:\s*["']?([\w.-]+)/m);
+      out.push({ rel, base: e.name, iid: m ? m[1] : null });
+    }
+  };
+  for (const d of DOC_ROOTS) walk(d, 0);
+  return out;
+}
+function documentsNaming(index, id) {
+  return index.filter((f) => f.iid === id || f.base === `${id}.md` || f.base.startsWith(`${id}-`)).map((f) => f.rel);
+}
+const isBriefName = (rel) => /brief/i.test(path.basename(rel));
+
 // ── the sweep ──────────────────────────────────────────────────────────────────────────────────
 
 function sweep(opts) {
@@ -197,6 +239,11 @@ function sweep(opts) {
     };
   }
   const idset = new Set(ids);
+  const profileInfo = engine.lanesFor(root);
+  const pmProfile = profileInfo.profile === 'pm-artifacts';
+  let docIndex = null;
+  let wfRange = null;
+  try { wfRange = engine.historyRange(root); } catch { wfRange = null; }
 
   // ── the ledgers, read once ────────────────────────────────────────────────────────────────────
   const ledgerFiles = {
@@ -260,9 +307,23 @@ function sweep(opts) {
   }
   const evalIds = new Set(ledgers.evals.rows.map(({ row }) => row && row.initiative_id).filter(Boolean));
   const acceptedIds = new Set(ledgers.acceptances.rows
-    .filter(({ row }) => row && (row.accepted === true || row.action === 'approve'))
+    .filter(({ row }) => row && row.accepted === true)
     .map(({ row }) => row.initiative_id).filter(Boolean));
 
+  // D77 — a row that looks like an approval and that the ladder does not count
+  for (const { row, line } of ledgers.acceptances.rows) {
+    if (!row || !row.initiative_id || !idset.has(row.initiative_id)) continue;
+    if (only && row.initiative_id !== only) continue;
+    if (row.accepted === true) continue;
+    if (row.action !== 'approve') continue;
+    findings.push(finding('acceptance-not-counted', {
+      id: row.initiative_id, file: path.relative(root, ledgerFiles.acceptances), line,
+      what: `an acceptances.jsonl row has action 'approve' and accepted '${row.accepted}' — the ladder counts only accepted: true`,
+      evidence: JSON.stringify(row).slice(0, 140),
+      hand: 'the sweep never writes a ledger: if this was an acceptance, the PM records it with scripts/record-acceptance.js; if it was something else, no action',
+    }));
+  }
+
   // ── delivery, read once ───────────────────────────────────────────────────────────────────────
   const del = delivery.deliveryIndex(root, ids);
   if (!del.ok) {
@@ -313,11 +374,18 @@ function sweep(opts) {
     const lane = (fm.lane || 'feature').trim() || 'feature';
 
     // dangling declared paths
-    for (const key of ['prd_path', 'rubric_path', 'explainer_path']) {
+    for (const key of pmProfile
+      ? ['prd_path', 'brief_path', 'doc_path', 'rubric_path', 'explainer_path']
+      : ['prd_path', 'rubric_path', 'explainer_path']) {
       const v = String(fm[key] || '').trim();
       if (!v) continue;
       if (fs.existsSync(path.join(root, v))) continue;
-      const cands = candidatesFor(root, L, key, id);
+      let cands;
+      if (key === 'brief_path' || key === 'doc_path') {
+        if (!docIndex) docIndex = buildDocIndex(root);
+        const named = documentsNaming(docIndex, id);
+        cands = named.filter((f) => (key === 'brief_path') === isBriefName(f));
+      } else cands = candidatesFor(root, L, key, id);
       findings.push(finding('dangling-path', {
         id, file: recRel,
         what: `${key} points at '${v}', which is not in the repository`,
@@ -332,6 +400,72 @@ function sweep(opts) {
       }));
     }
 
+    // D77 — a lane the profile does not offer
+    {
+      const declared = String(fm.lane || '').trim();
+      if (declared && !profileInfo.lanes.includes(declared)) {
+        const applied = pmProfile ? 'prd' : 'feature';
+        findings.push(finding('lane-outside-profile', {
+          id, file: recRel,
+          what: `lane '${declared}' is not a ${profileInfo.profile} lane`,
+          evidence: `the engine applies '${applied}' instead; this repository offers: ${profileInfo.lanes.join(', ')}`,
+          hand: `choose one of: ${profileInfo.lanes.join(', ')} — the lane is the PM's choice, so it is reported and never rewritten`,
+        }));
+      }
+    }
+
+    // D77 — a finished document that no record points at (document profile)
+    if (pmProfile) {
+      if (!docIndex) docIndex = buildDocIndex(root);
+      const named = documentsNaming(docIndex, id);
+      const declaredKeys = ['brief_path', 'prd_path', 'doc_path'].map((k) => String(fm[k] || '').trim()).filter(Boolean);
+      const unref = named.filter((f) => !declaredKeys.includes(f));
+      const briefEmpty = !String(fm.brief_path || fm.prd_path || '').trim();
+      const docEmpty = !String(fm.doc_path || '').trim();
+      if (unref.length && (briefEmpty || docEmpty)) {
+        let repair = null;
+        let hand = null;
+        if (unref.length === 1) {
+          const key = isBriefName(unref[0]) ? (briefEmpty ? 'brief_path' : null) : (docEmpty ? 'doc_path' : null);
+          if (key) repair = { kind: 'add-key', file: recRel, key, from: '', to: unref[0] };
+          else hand = `${unref[0]} names this initiative, but the key it would fill is already set — decide by hand`;
+        } else hand = `${unref.length} documents name this initiative (${unref.join(', ')}) — choosing which is the brief and which the deliverable is a judgement, so it is reported rather than guessed`;
+        findings.push(finding('unpointed-artifact', {
+          id, file: recRel,
+          what: `${unref.length} document${unref.length > 1 ? 's name' : ' names'} this initiative and no path key points at ${unref.length > 1 ? 'them' : 'it'}: ${unref.join(', ')}`,
+          evidence: `brief_path/prd_path ${briefEmpty ? 'is empty' : 'is set'}; doc_path ${docEmpty ? 'is empty' : 'is set'}`,
+          repair, hand,
+        }));
+      }
+    }
+
+    // D77 — what the ladder says against the record's own words, and against its own basis rule
+    if (wfRange) {
+      let wf = null;
+      try { wf = engine.computeWorkflow(id, { root, range: wfRange }); } catch { wf = null; }
+      if (wf && wf.ok && Array.isArray(wf.steps)) {
+        for (const st of wf.steps) {
+          if (st.status === 'done' && st.basis && st.basis.source === 'none' && st.key !== 'quality') {
+            findings.push(finding('done-without-basis', {
+              id, file: recRel,
+              what: `step '${st.key}' reads done and names no file, ledger or commit history`,
+              evidence: String(st.evidence || '').slice(0, 120),
+              hand: `the engine decided '${st.key}' from something the detail pane cannot open — fix the rung to name what it read`,
+            }));
+          }
+        }
+        const claim = String(fm.status || '').trim();
+        const gate = wf.steps.find((st) => st.key === 'accept' || st.key === 'approved');
+        if (/^(accepted|approved|complete|completed|done|delivered|shipped)\b/i.test(claim) && gate && gate.status !== 'done' && gate.status !== 'na') {
+          findings.push(finding('status-claims-ahead', {
+            id, file: recRel,
+            what: `status says '${claim.slice(0, 60)}' while the ${gate.key} step is ${gate.status}`,
+            evidence: String(gate.evidence || '').slice(0, 120),
+          }));
+        }
+      }
+    }
+
     // damaged frontmatter values
     for (const [key, v] of Object.entries(fm)) {
       const dmg = damagedValue(v);
@@ -553,6 +687,15 @@ function applyRepairs(res, opts) {
     for (const f of group) {
       const r = f.repair;
       const before = frontmatterValue(next, r.key);
+      if (r.kind === 'add-key') {
+        // One key, only when it is still absent or empty. A value the PM wrote since the sweep ran wins.
+        if (before !== null && before.trim() !== '') { skipped.push({ finding: f, why: `${r.key} was set since the sweep ran` }); continue; }
+        const edited = before === null ? insertFrontmatterKey(next, r.key, r.to) : setFrontmatterValue(next, r.key, r.to);
+        if (edited === next) { skipped.push({ finding: f, why: `${key} has no frontmatter to add ${r.key} to` }); continue; }
+        next = edited;
+        applied.push({ class: f.class, file: key, key: r.key, before: '(not set)', after: r.to.slice(0, 90) });
+        continue;
+      }
       if (before === null) { skipped.push({ finding: f, why: `${r.key} is no longer in the frontmatter` }); continue; }
       let after;
       if (r.kind === 'repoint') {
@@ -580,6 +723,15 @@ function frontmatterValue(text, key) {
   }
   return null;
 }
+/** Insert `key: value` as the last line of the leading frontmatter; the text is returned unchanged when there is none. */
+function insertFrontmatterKey(text, key, value) {
+  const lines = String(text).split('\n');
+  if (lines[0] !== '---') return text;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === '---') { lines.splice(i, 0, `${key}: ${value}`); return lines.join('\n'); }
+  }
+  return text;
+}
 function setFrontmatterValue(text, key, value) {
   const lines = String(text).split('\n');
   for (let i = 0; i < lines.length; i++) {

package/payload/skills/design-brief.skill

@@ -38,12 +38,11 @@ definition of *what to design* and the hard constraints, agreed before any desig
 
 ## Procedure
 
-0. **Grill before you brief** (the [prd skill](/skills/prd.skill)'s step-0 discipline, applied
-   to design intent): where the PM's aesthetic or structural intent is ambiguous, ask **one question
-   at a time with a recommended answer**, stop at unambiguous — no cap; a batch questionnaire is not
-   compliant. Look up what the environment answers (the capability ledger, the design system, the
-   promoted prototype); the taste calls are the PM's (D12). The recorded cost of skipping this is the
-   console-redesign series — "too many navigations" was stated once and unhonored twice.
+0. **Ask before you brief.** Where the PM's aesthetic or structural intent is ambiguous, follow the
+   [requirements-elicitation skill](/skills/requirements-elicitation.skill). Look up what the
+   environment answers (the capability ledger, the design system, the promoted prototype); the taste
+   calls are the PM's. The recorded cost of skipping this is the console-redesign series — "too many
+   navigations" was stated once and unhonored twice.
 1. **Confirm the anchor.** The initiative has a PRD and an anchor — a parent KR, or a declared
    health budget `health:<id>` (D59). The brief does not re-argue *whether*
    to build the surface; it says how it should look.

package/payload/skills/discovery.skill

@@ -71,5 +71,4 @@ initiative; prototype code deleted or explicitly quarantined.
 
 ## Level 3 sub-cases
 
-- None yet. (Multi-question research programs spanning several spikes: author
-  `discovery-program.md` on first need.)
+- None yet.

package/payload/skills/eval-rubric.skill

@@ -79,11 +79,8 @@ Before any work begins, the generator and evaluator **agree on done-criteria**
 contract stage of the [SDLC loop](/okf/core/concepts/sdlc-loop.md). A rubric is incomplete without
 one.
 
-**Reach the criteria by grilling, not assumption** (the [prd skill](/skills/prd.skill)'s step-0
-discipline applies here too): where the PM's intent is ambiguous, ask **one question at a time with a
-recommended answer**, stop at unambiguous — no cap, and a batch questionnaire is not compliant. If a
-fact can be found by exploring the environment, look it up rather than asking — the decisions are the
-PM's (D12). **Write criteria for durability:** behavioral contracts and interfaces, never file paths
+**Reach the criteria by asking, not assumption.** Where the PM's intent is ambiguous, follow the
+[requirements-elicitation skill](/skills/requirements-elicitation.skill). **Write criteria for durability:** behavioral contracts and interfaces, never file paths
 or line numbers (they stale while work waits); each criterion independently verifiable.
 
 **Format:**

package/payload/skills/pmos-router.skill

@@ -63,6 +63,7 @@ router is the bug (fix it via the weekly harness scan).
 | "**Production is broken**" | **Incident lane** | `type: incident`; fix now, record post-hoc within 48h at `prd_path` (the one sanctioned inversion; [incident template](/okf/core/templates/incident-record-template.md)) | Initiative Gate (record, post-hoc) |
 | A **text deliverable** (landing page, microcopy, release notes, campaign) | **Content lane** | `type: content`; content brief at `prd_path`, rubric recommended not required (D58); [copywriting skill](/skills/copywriting.skill). Copy for a prototype rides the prototype instead (D60) | Initiative Gate (content brief) |
 | **Upkeep** — refactor/ops/security with no honest KR | **Chore lane, health-anchored** | `type: chore`; one-paragraph intent in `status`; anchor `health:<id>` from [health-budgets](/planning/okrs/health-budgets.md) (D59) — never a faked KR | Initiative Gate (intent + anchor) |
+| "**Gather**, **clarify** or **sharpen** the requirements" — the PM has a vague ask or notes from gathering and no brief yet | **Requirements elicitation** (before the lane's first artifact) | [requirements-elicitation skill](/skills/requirements-elicitation.skill) → `planning/briefs/<id>-requirements.md` at `brief_path`; reads the lane's input from `scripts/lane-defs.js` and the notes `gather-requirements` filed (D71); the PM confirms each note item. It does not choose the lane and does not write the PRD | none (the brief is never a gate) |
 
 **Every route** still takes the universal steps: anchored initiative row (`create_initiative`),
 branch `initiative/<id>`, and the human Acceptance Gate at the end (D12) — the router never bypasses
@@ -97,5 +98,5 @@ Check your position at any time with `node scripts/workflow-state.js <id>`.
   already decided to explore, go straight to prototype.
 - **Anchor-free trivia** (a typo, a broken link): the `no-initiative` label, no lane. Real work
   never takes the hatch.
-- **Unknown shape after the checks:** ask the PM one routing question with a recommended answer —
-  do not guess a lane.
+- **Unknown shape after the checks:** ask the PM one routing question, as the
+  [requirements-elicitation skill](/skills/requirements-elicitation.skill) describes. Do not guess a lane.

package/payload/skills/prd.skill

@@ -30,22 +30,17 @@ agreed.
 
 ## Procedure
 
-0a. **Existing surface? Understand it first — before grilling.** If specifying this honestly
+0a. **Existing surface? Understand it first — before asking.** If specifying this honestly
    requires reading code that already exists, an [explain-surface](/skills/explain-surface.skill)
    pass runs on that region **first**, in a fresh context and **not by you**. Its *Open questions*
-   section is a declared input to the grilling below: those are the things that could not be
+   section is a declared input to the questions in step 0: those are the things that could not be
    determined from the code, and they must be resolved with the PM or carried explicitly into the
    PRD's risks — never silently answered by assumption. Greenfield → skip. This exists because step 0b's
    boundary rule, on its own, gives the **agent** the understanding and the PM none.
-0. **Grill before you write.** Before any authoring, interrogate the PM's intent as a dialogue —
-   **one question at a time, a recommended answer offered with each**, no authoring until shared
-   understanding is confirmed. Stop when the intent is **unambiguous**, not at a count — there is
-   deliberately **no question cap** (under-specification needs unlimited digging; a redundant
-   question is a quality bug, not a quantity bug). A batch questionnaire is **not** compliant with
-   this step. Boundary rule, near-verbatim from AGENTS.md: *if a fact can be found by exploring the
-   environment, look it up rather than asking — the decisions, though, are the PM's* (D12 at
-   optimal altitude). A stated requirement that later goes unhonored in a build (the recorded
-   "too many navigations" class) is exactly what this step exists to pin down in writing.
+0. **Ask before you write.** Follow the [requirements-elicitation skill](/skills/requirements-elicitation.skill):
+   its asking rule holds here, and no authoring starts until the PM confirms the shared understanding.
+   A stated requirement that later goes unhonored in a build (the recorded "too many navigations"
+   class) is what this step pins down in writing.
 1. **Anchor to strategy first.** Identify the parent KR in the
    [OKR tree](/okf/core/concepts/okr-tree.md) — or, for maintenance work with no honest KR, the
    declared [health budget](/okf/core/concepts/health-anchors.md) (`health:<id>`, D59). If the
@@ -107,8 +102,7 @@ its situating sentence (D58); the eval rubric is queued to be written first.
 
 ## Level 3 sub-cases
 
-- Multi-product or platform PRDs that span more than one `product_slug`: see `prd-multiproduct.md`
-  (author on first need).
+- None yet.
 - Spike / discovery work where the deliverable is a learning, not a feature, is **not a PRD
   case** — take the discovery lane ([D56](/okf/products/pmos/adr/d56-initiative-lanes.md)):
   [discovery skill](/skills/discovery.skill) +

package/payload/skills/requirements-elicitation.skill

@@ -0,0 +1,231 @@
+---
+name: requirements-elicitation
+description: Turn a vague ask, or notes the PM gathered, into a requirements brief by asking the PM questions one at a time. Use when the PM wants to gather, clarify or sharpen requirements, or before any lane writes its first artifact (PRD, spike brief, fix specification, content brief).
+version: 1.0.0
+owner: wawan
+risk: low
+category: planning
+scope: read:okf, read:planning, read:state, write:planning/briefs
+---
+
+# requirements-elicitation — Ask until the requirement is sharp
+
+This skill is the one place where PMOS states how an agent asks the PM questions. It also
+holds the questions each lane needs. Its output is a requirements brief that a PRD, a spike
+brief or a fix specification starts from. It does not write those documents.
+
+> **Format note:** this skill follows [SKILL-FORMAT](/skills/SKILL-FORMAT.md). The text is
+> instructional (class A of [technical-writing-ste](/skills/technical-writing-ste.skill)).
+
+## When to use vs. not
+
+- **Use** when the PM asks to gather, clarify or sharpen requirements.
+- **Use** before the first artifact of any lane, when the intent is not yet unambiguous.
+- **Do not use** to decide the lane. That is the [pmos-router](/skills/pmos-router.skill).
+- **Do not use** to judge whether to build at all. That is the
+  [strategic-brief](/skills/strategic-brief.skill).
+- **Do not use** when an instance of the idea is needed before the PM can judge it. Route to the
+  prototype lane first.
+
+## The asking rule
+
+This rule holds in every step below. Other skills point here and do not repeat it.
+
+1. Ask one question at a time.
+2. Give a recommended answer with each question.
+3. Do not set a limit on the number of questions. Stop when the intent is unambiguous.
+4. Do not send a batch questionnaire. A batch does not satisfy this rule.
+5. Look up each fact that the repository or the record can answer. Do not ask the PM for it.
+6. Leave each decision to the PM.
+7. Write nothing until the PM confirms the shared understanding.
+
+## Procedure
+
+1. **Find the lane.** Read the initiative record and its `type`. Run
+   `node scripts/workflow-state.js --lanes --json` (in a kit repository the script is
+   `pmos/scripts/workflow-state.js`). Find the lane in `defs`.
+   State the lane's `input`, `output` and `done` in plain words before the first question.
+   *Done when:* the PM has seen the lane's input, output and done-rule.
+
+   If the script is missing or the lane is not in `defs`, say so. Ask the PM which lane applies.
+   Do not guess a question set.
+
+2. **Look up what exists.** Read the record, the PRD or brief if one exists, the OKR the
+   record names, and the explainer if the surface exists. Collect the facts you found.
+   *Done when:* every fact you will use has a source, and none of them is a question for the PM.
+
+3. **Read the gathered notes.** List `<state>/requirements/*.md`. `<state>` is `pmos/state/`
+   if it exists, and `planning/` if not. Select each item whose `initiative` names this
+   initiative. Show each item to the PM with its pointer and its `confidence`. Ask for one
+   answer per item: confirmed, rejected or deferred. Record the answer.
+   - A confirmed item goes in the brief under *Decisions*, with its pointer.
+   - A rejected item is dropped. Name it in *Gathered notes used* as rejected.
+   - A deferred item goes in *Open questions*.
+   - An item with `confidence: unconfirmed` stays unconfirmed until the PM answers. Never write
+     it as a fact.
+   - Name a note that does not parse. Skip it.
+   - If no notes exist, say so and continue.
+
+   Never edit a note. The notes are read-only drafts (D71).
+   *Done when:* every selected item has an answer, or the PM has said to skip the notes.
+
+4. **Ask the topic questions.** Work through the [question inventory](#question-inventory).
+   Skip a topic the lane's input does not need, and say that you skipped it.
+   Skip a question that step 2 or step 3 already answered.
+   *Done when:* each topic is answered, skipped with a reason, or listed in *Open questions*.
+
+5. **Ask the lane questions.** Find the lane in [Question sets by lane](#question-sets-by-lane).
+   Ask each question there that the earlier steps did not answer.
+   *Done when:* every element of the lane's `input` has an answer or an *Open questions* entry.
+
+6. **Confirm.** Say the shared understanding back to the PM in one short list. Ask the PM to
+   confirm or correct it.
+   *Done when:* the PM has confirmed. If the PM corrects it, go back to step 4.
+
+7. **Write the brief.** Copy the
+   [requirements-brief-template](/okf/core/templates/requirements-brief-template.md). Fill every
+   section from the confirmed answers, in the PM's words where the PM gave words. Write it to
+   `planning/briefs/<id>-requirements.md`. Set `brief_path` on the initiative record. If the lane
+   uses `prd_path` for its first artifact and that file does not exist yet, tell the PM that the
+   brief is the input and that the lane's own skill writes `prd_path`.
+   *Done when:* the file exists, no section is empty, and `brief_path` is set.
+
+8. **Hand over.** Name the next skill for the lane: [prd](/skills/prd.skill) for
+   feature and new-feature, [discovery](/skills/discovery.skill) for discovery,
+   [copywriting](/skills/copywriting.skill) for content, and the lane's own
+   template for the others. State the open questions that remain.
+   *Done when:* the PM knows what comes next and what is still open.
+
+## Question inventory
+
+Each topic has an opening question. Add follow-up questions when the answer is vague.
+
+| Topic | Opening question |
+|---|---|
+| Problem and user | Who has this problem, and what do they do today instead? |
+| Evidence | What shows that the problem is real: a number, a ticket, a quote, an incident? |
+| Constraints | What is fixed: a date, a budget, a technology, a rule or a promise already made? |
+| Stakeholders and decision owner | Who is affected, who must agree, and who decides if they disagree? |
+| Dependencies | What must exist, or be done by someone else, before this can work? |
+| Data | What data does this read or change, and who owns it? |
+| Non-functional needs | What must hold about speed, security, privacy, access or cost? |
+| Risks | What is the worst way this fails, and how would we notice? |
+| Success measure | Which measure moves if this works, from what value to what value, by when? |
+| Out of scope | What will this not do, even though someone might expect it to? |
+
+## Question sets by lane
+
+Each lane has its own heading. The headings use the lane names in `scripts/lane-defs.js`.
+A lane name that both profiles use (discovery, chore) has one set.
+
+### Lane `feature`
+
+1. What behaviour changes for the user, in one sentence?
+2. Does the surface exist today? If yes, what does it do now?
+3. Which KR or health budget does this serve?
+4. Can the PM judge this from a description, or must the PM see an instance first?
+5. What would the PM check by hand to accept it?
+
+### Lane `new-feature`
+
+1. Who has the problem, and how often does it happen?
+2. What shows that it is real?
+3. What do users do today?
+4. What must a first version do, and what can wait?
+5. What would make the PM drop it?
+
+### Lane `improvement`
+
+1. What does the feature do now? Look it up first.
+2. What is wrong or missing, and for whom?
+3. Which measure should the change move, and by how much?
+4. What must stay the same?
+5. How will we tell that it worked?
+
+### Lane `bug-fix`
+
+1. What are the steps that reproduce it?
+2. What is the expected result?
+3. What is the actual result?
+4. How severe is it, and who is affected?
+5. Is there a workaround?
+
+### Lane `discovery`
+
+1. What is the question, in one sentence?
+2. What is unknown, and what is already known?
+3. What evidence would end the spike?
+4. What would make this worth picking up, and what would make it worth dropping?
+5. How long may it take?
+
+### Lane `chore`
+
+1. What is the intent, in one paragraph?
+2. Which health budget does it serve?
+3. What must not change?
+4. How will the PM see that it is done?
+
+### Lane `incident`
+
+1. What broke, and who noticed?
+2. What is the cause?
+3. What was the repair, and is it permanent?
+4. What stops it from happening again?
+5. When was it fixed? The record is due within 48 hours.
+
+### Lane `content`
+
+1. Who reads it, and what should they do after?
+2. What is the one message?
+3. What tone and length does the reader expect?
+4. What facts must it contain, and where are they?
+5. Does the PM want a rubric?
+
+### Lane `prototype`
+
+1. What judgement does the PM need to make?
+2. Which format fits the specimens: a screen, a sample output, a transcript or a schema?
+3. What should the 2–3 specimens differ on?
+4. Which conventions does the class need before the specimens (design system, skill format)?
+
+### Lane `prd`
+
+1. What is the question the document answers?
+2. Who reads it?
+3. Which decision does it inform?
+4. What do the readers already know?
+
+### Lane `strategy`
+
+1. What is the question the document answers?
+2. Who reads it?
+3. Which decision does it inform?
+4. Over what period?
+
+### Lane `project-plan`
+
+1. What is in scope, and what is out?
+2. Who is on it, and for how much of their time?
+3. Which dates are fixed, and who fixed them?
+4. What does it depend on?
+
+### Lane `decision-record`
+
+1. What are the options?
+2. Which one was chosen, and by whom?
+3. What is the reason?
+4. What would reverse the choice?
+
+### Lane `report`
+
+1. What period or subject does it cover?
+2. Who reads it?
+3. What should the reader do after reading?
+4. Which sources does it use, and which can it not reach?
+
+## Failure behaviour
+
+- The lane definition cannot be read: say so, and ask the PM which lane applies.
+- No gathered notes exist: say so, and continue.
+- A note does not parse: name it, and skip it.
+- The PM leaves a question open: write it under *Open questions*. Do not answer it.

package/payload/skills-native/design-brief/SKILL.md

@@ -40,12 +40,11 @@ definition of *what to design* and the hard constraints, agreed before any desig
 
 ## Procedure
 
-0. **Grill before you brief** (the [prd skill](/skills/prd.skill)'s step-0 discipline, applied
-   to design intent): where the PM's aesthetic or structural intent is ambiguous, ask **one question
-   at a time with a recommended answer**, stop at unambiguous — no cap; a batch questionnaire is not
-   compliant. Look up what the environment answers (the capability ledger, the design system, the
-   promoted prototype); the taste calls are the PM's (D12). The recorded cost of skipping this is the
-   console-redesign series — "too many navigations" was stated once and unhonored twice.
+0. **Ask before you brief.** Where the PM's aesthetic or structural intent is ambiguous, follow the
+   [requirements-elicitation skill](/skills/requirements-elicitation.skill). Look up what the
+   environment answers (the capability ledger, the design system, the promoted prototype); the taste
+   calls are the PM's. The recorded cost of skipping this is the console-redesign series — "too many
+   navigations" was stated once and unhonored twice.
 1. **Confirm the anchor.** The initiative has a PRD and an anchor — a parent KR, or a declared
    health budget `health:<id>` (D59). The brief does not re-argue *whether*
    to build the surface; it says how it should look.

package/payload/skills-native/discovery/SKILL.md

@@ -73,5 +73,4 @@ initiative; prototype code deleted or explicitly quarantined.
 
 ## Level 3 sub-cases
 
-- None yet. (Multi-question research programs spanning several spikes: author
-  `discovery-program.md` on first need.)
+- None yet.

package/payload/skills-native/eval-rubric/SKILL.md

@@ -81,11 +81,8 @@ Before any work begins, the generator and evaluator **agree on done-criteria**
 contract stage of the [SDLC loop](/okf/core/concepts/sdlc-loop.md). A rubric is incomplete without
 one.
 
-**Reach the criteria by grilling, not assumption** (the [prd skill](/skills/prd.skill)'s step-0
-discipline applies here too): where the PM's intent is ambiguous, ask **one question at a time with a
-recommended answer**, stop at unambiguous — no cap, and a batch questionnaire is not compliant. If a
-fact can be found by exploring the environment, look it up rather than asking — the decisions are the
-PM's (D12). **Write criteria for durability:** behavioral contracts and interfaces, never file paths
+**Reach the criteria by asking, not assumption.** Where the PM's intent is ambiguous, follow the
+[requirements-elicitation skill](/skills/requirements-elicitation.skill). **Write criteria for durability:** behavioral contracts and interfaces, never file paths
 or line numbers (they stale while work waits); each criterion independently verifiable.
 
 **Format:**

package/payload/skills-native/pmos-router/SKILL.md

@@ -65,6 +65,7 @@ router is the bug (fix it via the weekly harness scan).
 | "**Production is broken**" | **Incident lane** | `type: incident`; fix now, record post-hoc within 48h at `prd_path` (the one sanctioned inversion; [incident template](/okf/core/templates/incident-record-template.md)) | Initiative Gate (record, post-hoc) |
 | A **text deliverable** (landing page, microcopy, release notes, campaign) | **Content lane** | `type: content`; content brief at `prd_path`, rubric recommended not required (D58); [copywriting skill](/skills/copywriting.skill). Copy for a prototype rides the prototype instead (D60) | Initiative Gate (content brief) |
 | **Upkeep** — refactor/ops/security with no honest KR | **Chore lane, health-anchored** | `type: chore`; one-paragraph intent in `status`; anchor `health:<id>` from [health-budgets](/planning/okrs/health-budgets.md) (D59) — never a faked KR | Initiative Gate (intent + anchor) |
+| "**Gather**, **clarify** or **sharpen** the requirements" — the PM has a vague ask or notes from gathering and no brief yet | **Requirements elicitation** (before the lane's first artifact) | [requirements-elicitation skill](/skills/requirements-elicitation.skill) → `planning/briefs/<id>-requirements.md` at `brief_path`; reads the lane's input from `scripts/lane-defs.js` and the notes `gather-requirements` filed (D71); the PM confirms each note item. It does not choose the lane and does not write the PRD | none (the brief is never a gate) |
 
 **Every route** still takes the universal steps: anchored initiative row (`create_initiative`),
 branch `initiative/<id>`, and the human Acceptance Gate at the end (D12) — the router never bypasses
@@ -99,5 +100,5 @@ Check your position at any time with `node scripts/workflow-state.js <id>`.
   already decided to explore, go straight to prototype.
 - **Anchor-free trivia** (a typo, a broken link): the `no-initiative` label, no lane. Real work
   never takes the hatch.
-- **Unknown shape after the checks:** ask the PM one routing question with a recommended answer —
-  do not guess a lane.
+- **Unknown shape after the checks:** ask the PM one routing question, as the
+  [requirements-elicitation skill](/skills/requirements-elicitation.skill) describes. Do not guess a lane.