create-pmos 0.38.5 → 0.38.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pmos",
-  "version": "0.38.5",
+  "version": "0.38.6",
   "description": "Scaffold the PMOS portable kit — run the PMOS product-management workflow (initiative → lane-fit spec → contract → build → three gates, with work-type lanes for features, research, maintenance, incidents, and content) entirely inside your own repo, with all state as git-versioned files. Includes `workflow-sweep`, which audits the state every board derives from and separates real defects from work you simply have not done. `create-pmos workspace` also installs + launches the local Terminal Workspace GUI. No database, no network, no telemetry.",
   "license": "MIT",
   "bin": {

package/payload/AGENTS.md

@@ -81,7 +81,7 @@ Every initiative carries a `type` — the lane picks what the gate requires **be
    - **Choose the model for the work (D75).** Before you delegate a sub-task or start a long routine one, run `node pmos/scripts/pmos-model.js recommend "<the work>"`: it returns a tier (`fast` for routine, `balanced`, `deep` where a mistake is costly to find later), the model and effort it maps to in the PM's policy, and why. Use it; do not pick the strongest model for everything. Review and evaluation work is pinned and is never downgraded.
    - **Documents you write here follow OKF v0.2 (D73).** `type`, `title`, `description`, then `generated: {by: claude-code/<skill>, at: "<ISO time>"}`, `sources: [{resource: "<link or id>", title: "…"}]` and `status: draft` — **one key per line, nothing indented** (the readers stop at the first indented line), no `timestamp`. Only the PM sets `status: stable` or adds `verified`. This does not apply to initiative records, tickets or ledgers. `node pmos/scripts/okf-upgrade.js .` reports what in this repository is not yet conformant.
    - **Existing surface → the PM needs the understanding too.** That retrieval warms *you*. When the work touches something that already exists — the test is *would specifying this honestly require reading code that already exists?* — run `skills/explain-surface.skill` on that region **before** the brief/PRD is authored, in a fresh context and **not** by the agent that will write it. Standard for existing surfaces, skipped for greenfield. Without it, the agent acquires the understanding and the **PM approves a spec built on facts they never saw**.
-4. Anchor: the initiative file must exist at stage `intake`/`spec` with its **lane's** spec/eval artifacts authored **before** build (eval-first, D13, generalized per lane — see the lane table above; `feature` = PRD + rubric; the incident lane alone records post-hoc). Contract per lane: `feature` = the rubric's sprint-contract section with the PM's explicit `PM_approved: true`; `discovery` = the PM-approved spike brief (question + timebox); `chore` = the stated intent; `content` = the PM-approved content brief; `prototype` = the PM-approved quick brief (the judgement exercised + the specimen format) — and **no rubric**, which is the decision, not an omission. No work before the lane's approval. Feature-lane `test_method`s SHOULD be executable checks written before build (D58) — wire `templates/product-ci-starter.yml` so tier 1 is never silently empty.
+4. Anchor: the initiative file must exist at stage `intake`/`spec` with its **lane's** spec/eval artifacts authored **before** build (eval-first, D13, generalized per lane — see the lane table above; `feature` = PRD + rubric; the incident lane alone records post-hoc). Contract per lane: `feature` = the rubric's sprint-contract section with the PM's explicit `PM_approved: true`; `discovery` = the PM-approved spike brief (question + timebox); `chore` = the stated intent; `content` = the PM-approved content brief; `prototype` = the PM-approved quick brief (the judgement exercised + the specimen format) — and **no rubric**, which is the decision, not an omission. No work before the lane's approval. When you question the PM to reach any of these, follow `skills/requirements-elicitation.skill`. Feature-lane `test_method`s SHOULD be executable checks written before build (D58) — wire `templates/product-ci-starter.yml` so tier 1 is never silently empty.
 5. Branch `initiative/<id>`; execute at control altitude; one commit per artifact.
 6. Self-evaluate against the contract — self-eval is unreliable; it is an input to the gates, never a verdict.
 7. Close the gates: **Quality** = this repo's CI plus the kit gate (`pmos/scripts/gate-initiative.sh`

package/payload/KIT-VERSION

@@ -1,3 +1,3 @@
-kernel-source: pmos@f5daae8
-assembled: 2026-10-02
+kernel-source: pmos@cb4d5ff
+assembled: 2026-10-03
 mode: vendor

package/payload/okf/core/templates/requirements-brief-template.md

@@ -0,0 +1,61 @@
+---
+type: Template
+title: Requirements Brief Template
+description: The scaffold for the brief that the requirements-elicitation skill writes — problem, evidence, constraints, stakeholders, dependencies, success measure, out of scope, open questions, gathered notes used and decisions. Copy into /planning/briefs/ as <id>-requirements.md and set it as the initiative's brief_path.
+tags: [template, requirements, elicitation, lanes]
+timestamp: 2026-10-03
+---
+
+# Requirements Brief Template
+
+**Situating context:** Authored with the `requirements-skills-overhaul` initiative. Each lane used to start from its own artifact with no shared record of what the PM said. The [requirements-elicitation skill](/skills/requirements-elicitation.skill) fills this brief from a dialogue with the PM. A PRD, a spike brief or a fix specification starts from it. Copy the block below into `/planning/briefs/<id>-requirements.md`. The copy is an operational instance, not OKF knowledge.
+
+> Usage: replace every `<…>` placeholder. Write each answer in the PM's words where the PM gave words. Leave no section empty: write `none` or move the item to *Open questions*. Never write an unconfirmed item as a fact.
+
+---
+
+```markdown
+# Requirements Brief: <initiative title>
+
+## Identity
+- initiative_id: <id>
+- lane: <lane name>
+- parent_KR: <objective or KR reference, or health:<id>>
+- date: <YYYY-MM-DD>
+
+## Problem and user
+<!-- Who has the problem, and what do they do today instead? -->
+
+## Evidence
+<!-- What shows that the problem is real? Give a source for each item. -->
+
+## Constraints
+<!-- What is fixed: dates, budget, technology, rules, promises 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, first. -->
+
+## Success measure
+<!-- The measure, its start value, its target and the date. -->
+
+## Out of scope
+<!-- What this will not do, even though someone might expect it to. -->
+
+## Lane answers
+<!-- The answers to the lane's own questions: bug report fields for a bug-fix,
+     the question and drop criteria for a discovery, and so on. -->
+
+## Open questions
+<!-- Each question the PM left open, and each deferred note item. Do not answer them here. -->
+
+## Gathered notes used
+<!-- For each note item shown to the PM: the pointer, its confidence, and the PM's answer
+     (confirmed, rejected or deferred). Write `none` if no notes existed. -->
+
+## Decisions
+<!-- The PM's confirmed decisions, in the PM's words. A confirmed note item goes here with
+     its pointer. -->
+```

package/payload/planning/evals/eval-calibration.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Eval calibration log"
 description: "Append-only record of every PM override of an evaluator verdict."
-generated: {by: process:create-pmos, at: "2026-10-02T23:30:04Z"}
+generated: {by: process:create-pmos, at: "2026-10-03T00:48:37Z"}
 status: stable
 ---
 

package/payload/planning/okrs/health-budgets.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Health budgets"
 description: "Closed registry of health-budget anchors (D59), edited only by the PM."
-generated: {by: process:create-pmos, at: "2026-10-02T23:30:04Z"}
+generated: {by: process:create-pmos, at: "2026-10-03T00:48:37Z"}
 status: stable
 ---
 

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.

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

@@ -32,22 +32,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
@@ -109,8 +104,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-native/requirements-elicitation/SKILL.md

@@ -0,0 +1,233 @@
+---
+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).
+license: MIT
+metadata:
+  pmos-version: 1.0.0
+  pmos-owner: wawan
+  pmos-risk: low
+  pmos-category: planning
+  pmos-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/state/discoveries.md

@@ -2,7 +2,7 @@
 type: Reference
 title: "Discoveries and friction log"
 description: "Append-only record of what runs discovered and where the process rubbed."
-generated: {by: process:create-pmos, at: "2026-10-02T23:30:04Z"}
+generated: {by: process:create-pmos, at: "2026-10-03T00:48:37Z"}
 status: stable
 ---
 

package/payload/state/log.md

@@ -2,6 +2,6 @@
 
 Newest first, ISO dates.
 
-## 2026-10-02
+## 2026-10-03
 
 - Adopted OKF v0.2 (D73).

package/workspace/package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.38.5",
+  "version": "0.38.6",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.38.5",
+  "version": "0.38.6",
   "private": true,
   "description": "PMOS Terminal Workspace — local companion hosting real PTYs beside the library and gates (D62)",
   "license": "MIT",

package/workspace/skills/gather-requirements.skill

@@ -4,6 +4,10 @@ label: "Gather requirements"
 description: "Read what changed in the PM's mail, chat, Jira, Confluence, calendar and meeting notes since the last note, and file one dated note of requirements — each with its source, how sure it is, and which initiative it touches."
 run: agent
 agent: claude
+version: 1.1.0
+owner: wawan
+risk: low
+scope: read:connectors, read:state, write:state/requirements
 output:
   - New or changed requirements
   - Validations and contradictions
@@ -20,17 +24,22 @@ Rules that always hold:
 4. NOTHING INVENTED. If a source is not reachable in this session, say so under "Sources reached and not reached". If nothing changed, say that. An honest empty note is correct.
 5. UNCONFIRMED IS ALLOWED. Mark every item `confidence: unconfirmed` or `confirmed` (confirmed = a person with authority said it in a decision, an approved document or a closed ticket). A note is evidence, never a decision or an acceptance.
 
-Procedure:
+Procedure (each step ends with a check that shows it is done):
 1. Find the state directory: `pmos/state/` if it exists, otherwise `planning/`. The note goes in `<state>/requirements/YYYY-MM-DD.md` (today's date). If today's file already exists, do NOT overwrite it: append a section `## Later run HH:MM`.
+   Done when: the target path is named, and an existing file is still intact.
 2. Read the previous note in that folder to learn the cutoff. With no previous note, look back 3 days.
+   Done when: you can state the cutoff as a date and time.
 3. Read the initiatives in `<state>/initiatives/` (or `planning/initiatives/`) so you can say which one an item touches. Match by what the item is about, not by keyword.
+   Done when: you have the list of initiative ids that an item can name.
 4. For each source you can reach, read what changed since the cutoff: mail, chat, Jira, Confluence, calendar events with their notes, meeting notes.
+   Done when: each source kind is either read or marked not reached.
 5. For each requirement found, write one item:
    - the requirement, in your words
    - pointer: kind · id or link · date · author
    - confidence: unconfirmed | confirmed
    - relation: validates | clarifies | extends | contradicts | none
    - initiative: its id, or `unmatched`
+   Done when: every item has all five fields and a pointer.
 6. Start the file with this frontmatter (OKF v0.2, D73). Every key is on ONE line — never indent a key under another, because the readers stop at the first indented line. Then the four sections above, in this order:
    ```
    ---
@@ -43,8 +52,11 @@ Procedure:
    ---
    ```
    `sources` lists every item the note is derived from (the same pointers you give per item). Do not add a `timestamp` and do not add `verified`: only the PM confirms a note.
+   Done when: the file starts with this frontmatter and holds the four sections in order.
 7. Under "Sources reached and not reached", list every source kind you tried, with `reached` or `not reached — <why>`, and the number of private items skipped.
+   Done when: every source kind you tried has a line, and the private count is stated.
 8. Finish by saying in one line how many items you filed and where. Do not commit; the PM's Sync carries the file.
+   Done when: the count and the path are said once, and no commit was made.
 
 Output contract — produce EXACTLY these sections, the same shape every run:
 - New or changed requirements