create-pmos 0.38.5 → 0.38.7

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/skills-native/technical-writing-ste/SKILL.md

@@ -41,7 +41,7 @@ Ask what the reader must do with it. Derive the class from the path, not from fe
 | Class | What the reader must do | Where it lives |
 |---|---|---|
 | **A — instructional** | **Act**, correctly, on one reading | `skills/**` · playbooks and runbooks · gate and CI failure strings · UI copy and microcopy · tool descriptions · template usage notes |
-| **B — descriptive** | **Understand**, not obey | `okf/**` concepts and references · explainers · `**/README.md` · design and data-model docs |
+| **B — descriptive** | **Understand**, not obey | `okf/**` concepts and references · explainers · `**/README.md` · design and data-model docs · agent-drafted status reports and stakeholder updates (`planning/reports/**`, `<state>/reports/**`) |
 | **C — argumentative** | **Weigh a judgement under uncertainty** | ADRs and decision records · `planning/prd/**` · briefs · the discoveries log · eval verdicts · PR bodies |
 
 The three classes are the rule. **The paths are your repo's, so write them down once.** In PMOS they
@@ -50,8 +50,10 @@ also cover `build-skills/**` and `okf/core/playbooks/**` (A), `planning/explaine
 cover your CLI output, your error strings and your component copy (A), and your architecture notes
 (B). When a path is not on your list, ask the question in column two and add the answer to the list.
 
-Two boundary rules. **Text the PM wrote is Class C**, whatever it is about. And the profile binds
-**new and modified text only** — never rewrite an existing corpus to satisfy it.
+Three boundary rules. **Text the PM wrote is Class C**, whatever it is about. The profile binds
+**new and modified text only** — never rewrite an existing corpus to satisfy it. And inside an
+agent-drafted status report or update, the request in *Needs your call* is **Class A**: the reader
+must act on it, so write one question, the options, your recommendation and the date.
 
 **Done when:** you can name the class and the row that put it there.
 

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-03T01:20:42Z"}
 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.7",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {

package/workspace/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmos-workspace",
-  "version": "0.38.5",
+  "version": "0.38.7",
   "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

package/workspace/skills/report-biweekly.skill

@@ -5,7 +5,7 @@ description: "Prepare the biweekly report as a draft, following the PM's own def
 run: agent
 agent: claude
 output:
-  - Summary
+  - Headline
   - Sections from the definition
   - Needs your call
   - Sources reached and not reached
@@ -40,14 +40,14 @@ Procedure:
    ---
    ```
    `definition` says whether the definition used is confirmed (`stable`) or only proposed (`draft`). Do not add a `timestamp` or `verified`.
-5. Under the frontmatter: a short Summary, then the sections the definition names in its order, then "Needs your call" (decisions or answers only the PM can give), then "Sources reached and not reached" (each source kind: reached or not reached and why; private items skipped).
-6. If the definition was a draft, say so in the first line of the Summary so the PM sees it.
+5. Under the frontmatter: a Headline (one or two sentences: what the reader most needs to know), then the sections the definition names in its order, then "Needs your call" (decisions or answers only the PM can give), then "Sources reached and not reached" (each source kind: reached or not reached and why; private items skipped).
+6. If the definition was a draft, say so in the first line of the Headline so the PM sees it.
 7. Finish by saying in one line where the draft is. Do not commit; the PM's Sync carries the file.
 
-Default shape, used ONLY when proposing a definition: a two-week summary: progress, decisions, risks, what is next.
+Default shape, used ONLY when proposing a definition: a two-week report: progress, decisions, risks, what is next. Use the report frame of D78: a Headline, then What moved, Risks and Metrics, then Needs your call and Sources reached and not reached.
 
 Output contract — produce EXACTLY these sections, the same shape every run:
-- Summary
+- Headline
 - Sections from the definition
 - Needs your call
 - Sources reached and not reached

package/workspace/skills/report-daily.skill

@@ -5,7 +5,7 @@ description: "Prepare the daily report as a draft, following the PM's own defini
 run: agent
 agent: claude
 output:
-  - Summary
+  - Headline
   - Sections from the definition
   - Needs your call
   - Sources reached and not reached
@@ -40,14 +40,14 @@ Procedure:
    ---
    ```
    `definition` says whether the definition used is confirmed (`stable`) or only proposed (`draft`). Do not add a `timestamp` or `verified`.
-5. Under the frontmatter: a short Summary, then the sections the definition names in its order, then "Needs your call" (decisions or answers only the PM can give), then "Sources reached and not reached" (each source kind: reached or not reached and why; private items skipped).
-6. If the definition was a draft, say so in the first line of the Summary so the PM sees it.
+5. Under the frontmatter: a Headline (one or two sentences: what the reader most needs to know), then the sections the definition names in its order, then "Needs your call" (decisions or answers only the PM can give), then "Sources reached and not reached" (each source kind: reached or not reached and why; private items skipped).
+6. If the definition was a draft, say so in the first line of the Headline so the PM sees it.
 7. Finish by saying in one line where the draft is. Do not commit; the PM's Sync carries the file.
 
-Default shape, used ONLY when proposing a definition: a one-page end-of-day summary: what moved, what is blocked, what needs the PM tomorrow.
+Default shape, used ONLY when proposing a definition: a one-page end-of-day report: what moved, what is blocked, what needs the PM tomorrow. Use the report frame of D78: a Headline, then What moved, Risks and Metrics, then Needs your call and Sources reached and not reached.
 
 Output contract — produce EXACTLY these sections, the same shape every run:
-- Summary
+- Headline
 - Sections from the definition
 - Needs your call
 - Sources reached and not reached

package/workspace/skills/report-monthly.skill

@@ -5,7 +5,7 @@ description: "Prepare the monthly report as a draft, following the PM's own defi
 run: agent
 agent: claude
 output:
-  - Summary
+  - Headline
   - Sections from the definition
   - Needs your call
   - Sources reached and not reached
@@ -40,14 +40,14 @@ Procedure:
    ---
    ```
    `definition` says whether the definition used is confirmed (`stable`) or only proposed (`draft`). Do not add a `timestamp` or `verified`.
-5. Under the frontmatter: a short Summary, then the sections the definition names in its order, then "Needs your call" (decisions or answers only the PM can give), then "Sources reached and not reached" (each source kind: reached or not reached and why; private items skipped).
-6. If the definition was a draft, say so in the first line of the Summary so the PM sees it.
+5. Under the frontmatter: a Headline (one or two sentences: what the reader most needs to know), then the sections the definition names in its order, then "Needs your call" (decisions or answers only the PM can give), then "Sources reached and not reached" (each source kind: reached or not reached and why; private items skipped).
+6. If the definition was a draft, say so in the first line of the Headline so the PM sees it.
 7. Finish by saying in one line where the draft is. Do not commit; the PM's Sync carries the file.
 
-Default shape, used ONLY when proposing a definition: a monthly review: outcomes against goals, decisions, risks, learning, next month.
+Default shape, used ONLY when proposing a definition: a monthly review: outcomes against goals, decisions, risks, learning, next month. Use the report frame of D78: a Headline, then What moved, Risks and Metrics, then Needs your call and Sources reached and not reached.
 
 Output contract — produce EXACTLY these sections, the same shape every run:
-- Summary
+- Headline
 - Sections from the definition
 - Needs your call
 - Sources reached and not reached

package/workspace/skills/report-special.skill

@@ -5,7 +5,7 @@ description: "Prepare a one-off report as a draft. The PM says what it is for; t
 run: agent
 agent: claude
 output:
-  - Summary
+  - Headline
   - Sections from the definition
   - Needs your call
   - Sources reached and not reached
@@ -26,7 +26,7 @@ Procedure:
 2. Find the state directory: `pmos/state/` if it exists, otherwise `planning/`. Call it <state>.
 3. If `<state>/reports/definitions/special.md` exists, read it for the house style and use it where it does not contradict what the PM just asked.
 4. Gather the material: the requirement notes in `<state>/requirements/`, the initiatives and acceptances, and every connected source you can reach that bears on the topic.
-5. Write the draft to `<state>/reports/special/YYYY-MM-DD-<short-topic-slug>.md`, then the sections the PM asked for, then "Needs your call" and "Sources reached and not reached". Start it with this frontmatter (OKF v0.2, D73). Every key is on ONE line — never indent a key under another:
+5. Write the draft to `<state>/reports/special/YYYY-MM-DD-<short-topic-slug>.md`, then a Headline (one or two sentences), then the sections the PM asked for (the report frame of D78 by default: What moved, Risks, Metrics), then "Needs your call" and "Sources reached and not reached". Start it with this frontmatter (OKF v0.2, D73). Every key is on ONE line — never indent a key under another:
    ```
    ---
    type: Reference
@@ -43,7 +43,7 @@ Procedure:
 7. Finish by saying in one line where the draft is. Do not commit; the PM's Sync carries the file.
 
 Output contract — produce EXACTLY these sections, the same shape every run:
-- Summary
+- Headline
 - Sections from the definition
 - Needs your call
 - Sources reached and not reached

package/workspace/skills/report-weekly.skill

@@ -5,7 +5,7 @@ description: "Prepare the weekly report as a draft, following the PM's own defin
 run: agent
 agent: claude
 output:
-  - Summary
+  - Headline
   - Sections from the definition
   - Needs your call
   - Sources reached and not reached
@@ -40,14 +40,14 @@ Procedure:
    ---
    ```
    `definition` says whether the definition used is confirmed (`stable`) or only proposed (`draft`). Do not add a `timestamp` or `verified`.
-5. Under the frontmatter: a short Summary, then the sections the definition names in its order, then "Needs your call" (decisions or answers only the PM can give), then "Sources reached and not reached" (each source kind: reached or not reached and why; private items skipped).
-6. If the definition was a draft, say so in the first line of the Summary so the PM sees it.
+5. Under the frontmatter: a Headline (one or two sentences: what the reader most needs to know), then the sections the definition names in its order, then "Needs your call" (decisions or answers only the PM can give), then "Sources reached and not reached" (each source kind: reached or not reached and why; private items skipped).
+6. If the definition was a draft, say so in the first line of the Headline so the PM sees it.
 7. Finish by saying in one line where the draft is. Do not commit; the PM's Sync carries the file.
 
-Default shape, used ONLY when proposing a definition: a weekly summary: progress against initiatives, decisions made, risks, what is next.
+Default shape, used ONLY when proposing a definition: a weekly report: progress against initiatives, decisions made, risks, what is next. Use the report frame of D78: a Headline, then What moved, Risks and Metrics, then Needs your call and Sources reached and not reached.
 
 Output contract — produce EXACTLY these sections, the same shape every run:
-- Summary
+- Headline
 - Sections from the definition
 - Needs your call
 - Sources reached and not reached

package/workspace/skills/weekly-report.skill

@@ -1,12 +1,13 @@
 ---
 name: weekly-report
 label: "Weekly report"
-description: "A weekly status report across the workspace — in flight, landed, needs-you, and a metrics pulse."
+description: "A weekly status report across the workspace — in flight, delivered (acceptance not recorded), accepted, needs-you, and a metrics pulse."
 run: deterministic
 surface: report
 output:
   - In flight
-  - Landed
+  - Delivered — acceptance not recorded
+  - Accepted
   - Needs you
   - Metrics pulse
 ---