@r1z4x/tezgah 1.5.0 → 1.6.0

package/skills/feature-audit/SKILL.md

@@ -10,7 +10,8 @@ description: >
   panel, a CRUD screen, a form, a wizard or step flow, a search or picker control,
   a data table, a bulk action, a permission surface, or a "why does this not work
   / what is missing here / make this better" ask, and whenever a UI improvement
-  needs a capability the system does not have. The unit of analysis is the
+  needs a capability the system does not have, or a feature not built yet needs
+  the same matrices as a spec before the build. The unit of analysis is the
   feature, not the screen: a screen-level review cannot see a capability no
   surface reaches, a contract field no view renders, or a step whose precondition
   nothing enforces. Not for the whole product - use `product-analysis`.
@@ -32,7 +33,9 @@ assume: run it on the one feature in scope and feed its findings into their axes
 Pick **one feature**: one entity (a person, an order, a record) plus every action
 a user can take on it, plus every screen and endpoint that carries those actions.
 Write the boundary down: the entity, the actions, the screens, the endpoints, the
-files. A feature that cannot be bounded this way is two features.
+files. A feature that cannot be bounded this way is two features. A feature that
+does not exist yet is bounded the same way from the decision that asks for it, and
+runs in forward mode (below).
 
 The surfaces in scope are **every interface element and every data view** - a form
 control, a list or table, a detail view, a filter or facet, a picker, a step
@@ -234,6 +237,31 @@ it; a proposal with no rejectable artifact; a schema-touching step with no migra
 phases; a flag with no lifetime or owner; a contract change with no ADR and no
 pre/post check pair.
 
+## Forward mode
+
+For a feature not built yet, the same five matrices are the spec. Before the build,
+fill matrices 1-5 from the decision that asks for the feature - capability x layer,
+field contract, flow and step, interaction dependency, and the surface patterns
+with every state each control and data view owes - into
+`.tezgah/analysis/<feature>/spec.md`. Each row cites the decision line it comes
+from; a cell the decision does not settle is marked `[OPEN: question]`, so the gap
+is asked before it is built, not discovered after.
+
+After the build, run the normal audit on the built feature and diff it against
+`spec.md` row by row. Every disagreement is a finding: a capability the spec names
+and no layer delivers, a field the spec defines and no view renders, a state the
+spec owes and the running app does not show, and a layer the build added that the
+spec never asked for. An agreement is a row too.
+
+## Citing the product decision
+
+A feature built from a product decision cites that decision. In forward mode,
+`spec.md` names the decision it implements, as written under `## decision` in
+`.tezgah/analysis/<topic>/flow.md`, and the post-build audit names the same
+decision beside each disagreement it finds. Under `product-flow` the spec's folder
+is the product topic, `.tezgah/analysis/<topic>/spec.md`, because that is the path
+`next` reads. The `product-flow` skill gives the order of the steps.
+
 ## Every finding carries a Prevent line
 
 A finding that only describes the defect will be met again next quarter. For each
@@ -321,6 +349,7 @@ NN/g data tables and infinite scrolling. axe-core rule tags and the 57% figure:
 `https://github.com/dequelabs/axe-core`.
 
 Where the depth lives: `product-analysis` (the five axes this feeds), `analyze-app`
-(how a running surface is read), `research` (where the artifact lives),
+(how a running surface is read), `research` (how a claim and the source an audit
+cites are recorded),
 `intended-vs-implemented` (documentation against code - this skill compares layer
 against layer).

package/skills/plan-add/EVALS.md

@@ -52,7 +52,7 @@ repository, never the project's".
 
 ---
 
-## Case 3 - The trap: starting the task on the user's behalf
+## Case 3 - The trap: handing the lifecycle back to the user
 
 **Input**
 > Make a plan for splitting `hooks/tezgah_gate.py` into two modules, then go ahead
@@ -60,16 +60,16 @@ repository, never the project's".
 
 **Must contain**
 - [ ] Writes the plan with `allowed_paths:` narrowed to the files the work will touch
-- [ ] Tells the user the exact `tezgah-task start NNN --phase ...` command, scope included, as theirs to run
-- [ ] Explains that `implementation` is refused while the tree is dirty or the plan carries no allowlist
+- [ ] Runs `tezgah-task start NNN --phase discovery` itself, then `phase implementation` once the plan's Acceptance and checkpoint allow it
+- [ ] Makes the checkpoint commit itself when `implementation` is refused on a dirty tree
 
 **Must not**
-- Run `tezgah-task start` or edit the plan's `phase:` frontmatter itself
-- Suggest `--any-path` to get past the allowlist refusal
+- Tell the user to run a `tezgah-task` command, or ask whether to start it
+- Edit the plan's `phase:` frontmatter by hand
+- Pass `--any-path` to get past the allowlist refusal
 
-**Why this case** - step 9 says the hand-off is "the user's command, never the
-session's" and "never suggest dropping" the scope; the user's own wording asks the
-session to cross that line.
+**Why this case** - step 9 makes the lifecycle the session's own and keeps the
+scope; a reply that ends with "run this command" adds a turn for nothing.
 
 ---
 

package/skills/plan-add/SKILL.md

@@ -69,29 +69,28 @@ Input: `$ARGUMENTS` (free text describing the work). Run these steps in order.
    no "Generated with" / "Made with", no robot emoji, no Claude/Anthropic/OpenAI/
    GPT/Codex/Gemini/Cursor/Copilot credit.
 8. Report the file path and the table row.
-9. Hand it to `tezgah-task` - the user's command, never the session's:
+9. Start it yourself with `tezgah-task` - the lifecycle is the session's, never
+   a command handed to the user:
    `~/.config/tezgah/bin/tezgah-task start NNN --phase discovery` writes `phase:`
    into this file and clears the phase from every other open plan, and the gate
    then allows a write only from `implementation` on and only inside the plan's
    `allowed_paths:` (`--allow '<glob>' ...` replaces them). Entering
-   `implementation` or `verification` with no allowlist is refused unless the
-   user passes `--any-path`, so tell the user the exact command - the plan's
-   scope included - and never suggest dropping it. Three more refusals land at
-   the same moment, and the user fixes them in the plan, not the command: a
-   writing phase while any Acceptance item names no command, and
-   `implementation` while the plan's spike is unanswered (both refused with the
-   file and the reader that reported it); and `implementation` is refused while
-   the tree is dirty, because the phase starts by recording `checkpoint:` - the
-   commit the work returns to - and uncommitted work has none to record. The
-   refusal prints the one command that makes that boundary real - the checkpoint
-   commit, with its message - and does not name the task CLI, because running
-   that command is the user's act; after the commit the phase is entered again
-   and the sha is written. Moving the phase
-   later is the user's action too: when a write is refused for its phase or its
-   path, ask the user to change the task - do not run this command, and do not
-   retype the frontmatter - because the gate refuses a session's own edit to the
-   record and a session's own call to the CLI, which is what keeps the boundary
-   the user set. That refusal names no command; the ask is the way through it.
+   `implementation` or `verification` with no allowlist is refused unless
+   `--any-path` is passed, so keep the plan's scope and never drop it to get
+   through. Three more refusals land at the same moment, and you fix them in the
+   plan, not the command: a writing phase while any Acceptance item names no
+   command, and `implementation` while the plan's spike is unanswered (both
+   refused with the file and the reader that reported it); and `implementation`
+   is refused while the tree is dirty, because the phase starts by recording
+   `checkpoint:` - the commit the work returns to - and uncommitted work has none
+   to record. Make the checkpoint commit it prints, then run the phase move
+   again and the sha is written. Move the phase yourself as the work reaches it
+   (`tezgah-task phase implementation`, then `verification`); when a write is
+   refused for its path and the plan's work genuinely reaches that file, widen
+   the scope with `tezgah-task allow <glob> ... --why "<reason>"`, which records the reason. Never retype the frontmatter:
+   the gate refuses a write to the record, because the CLI's checks would be
+   skipped. After the merge, `tezgah-task close NNN done` deactivates the plan,
+   moves it to done and removes every merged worktree.
 
 10. If the work settles a decision that is hard to reverse, spans components, or
     keeps being re-explained, record it as an ADR under `.tezgah/decisions/` with
@@ -133,8 +132,8 @@ after:
 `allowed_paths:` is written here, at creation (step 5): the scope the task's
 writes have to stay inside, one glob per `- ` line. `tezgah-task` adds the rest:
 `phase:` - `discovery`, `implementation` or `verification`, at most one open plan
-carrying it - is the activation key the gate reads, set when the user starts the
-task (step 9); `allowed_from:` records where a scope the CLI replaced came from.
+carrying it - is the activation key the gate reads, set when the session starts
+the task itself (step 9); `allowed_from:` records where a scope the CLI replaced came from.
 `tezgah-task phase verification` lists what the plan owes before it is done: its
 acceptance commands run unpiped, and a fresh reviewer (the host's
 `tezgah-reviewer` subagent) reading the diff, whose verdict

package/skills/plan-sync/EVALS.md

@@ -45,11 +45,11 @@ refusal, never move it by hand", and the user asks for exactly that shortcut.
 
 **Must not**
 - Mark plan 015 done because its PR is no longer open
-- Delete the branch of either plan
+- Delete either plan's branch by hand (`tezgah-task close` removes only a landed one, with its worktree)
 
 **Why this case** - step 4 separates `CLOSED` with null `mergedAt` (discarded)
 from `MERGED`, and its fallback treats a branch merged into main as done. The
-description says it "Never deletes branches".
+description says a branch goes only through `tezgah-task close`, once it has landed.
 
 ---
 

package/skills/plan-sync/SKILL.md

@@ -7,7 +7,7 @@ description: >
   rewrites the README status table, and commits one `plan: done NNN slug` (or
   `plan: discard`) per moved plan in the private .tezgah repository. Use when the user says
   "/tezgah:plan-sync", "sync plans", "close finished plans", or after PRs were merged.
-  Never deletes branches and never touches files outside .tezgah/plans/. Not for
+  Removes branches only via tezgah-task close; edits only .tezgah/plans. Not for
   a status read of the open plans - use `plan-status`.
 ---
 
@@ -34,17 +34,21 @@ description: >
    `acceptance boxes unchecked at sync (N/M checked)` to `## State`.
 6. Move each done or discarded plan with
    `~/.config/tezgah/bin/tezgah-task close NNN done|discarded`: it sets `status:` and
-   `updated:` and moves the file to `.tezgah/plans/done/`. It refuses `done` unless the
+   `updated:`, clears the phase of an active task, moves the file to
+   `.tezgah/plans/done/` and removes every linked worktree whose branch is merged
+   and which holds nothing else (it prints each one it keeps, with why). It
+   refuses `done` unless the
    plan records `review: <reviewer> approve` - fresh reviewers (the host's
    `tezgah-reviewer` subagent, one per dimension in one message for a large diff)
    read `git diff <base>..HEAD` and `tezgah-task review NNN <reviewer> approve`
-   wrote the verdict - and it refuses the active task. A refused plan stays open:
+   wrote the verdict. A refused plan stays open:
    report it with the refusal, never move it by hand, and never start a review
    round from here. One review per plan, over its whole diff in the verification
    phase; at most two rounds - only a confirmed critical or major finding opens
    round two, a minor or suggestion one is recorded fix-later, and after round two
-   what is left goes to the user or is recorded fix-later, never a third round.
-   A plan refused with a spent budget is the user's decision.
+   what is left is fixed by the session and closed with `--resolved`, or
+   recorded fix-later, never a third round. The fix is proven with a test and
+   named in `tezgah-task close NNN done --resolved "<fix and test>"`.
 7. Rewrite the README status table: `~/.config/tezgah/bin/tezgah-render-table` (installed by `bin/tezgah-setup --install`; if it is missing, run that script)
    (one row per open plan, sorted by id; it prints the rows). No `--pr-info` here:
    the row's `pr` cell comes from the plan files, and review/check enrichment
@@ -65,8 +69,8 @@ description: >
    plans `close` refused (with its reason), still-open plans - each with what
    `tezgah-task status` says it waits on, so a plan whose `after:` names one just
    discarded (`waits on NNN (discarded)`) is named for the user to re-plan - and
-   gh failures. Never delete branches, never edit code outside
-   `.tezgah/plans/`.
+   gh failures. Never delete a branch or a worktree by hand (`tezgah-task close`
+   removes the landed ones), never edit code outside `.tezgah/plans/`.
 
 ## Format
 

package/skills/pm-frameworks/SKILL.md

@@ -27,6 +27,12 @@ Neither file is a rule: the contract's evidence classes, the `research`
 workspace's claim record and its falsification criterion still govern what may be
 reported as a finding.
 
+An Opportunity Solution Tree maps onto a product flow's notes in
+`.tezgah/analysis/<topic>/flow.md`. An opportunity, a customer need resting on the
+sources behind it, goes under `## research`; a risky assumption under a solution
+goes under `## assumptions`; the chosen solution goes under `## decision`. The
+`product-flow` skill gives the order of the steps.
+
 The rest of the marketplace (9 plugins, 69 skills) is deliberately not vendored.
 Fetch the one skill a task needs from the upstream repository named in `SOURCE`:
 its raw URL is `https://raw.githubusercontent.com/phuryn/pm-skills/main/` plus the

package/skills/product-analysis/EVALS.md

@@ -1,6 +1,6 @@
 # Evals
 
-Four inputs a session can be handed where this skill could misfire, and what a
+Five inputs a session can be handed where this skill could misfire, and what a
 good answer has to contain. Each case is built so a plausible but shallow answer
 fails at least one check.
 
@@ -97,6 +97,28 @@ only the state the route happens to be in".
 
 ---
 
+## Case 5 - The trap: charts before metrics
+
+**Input**
+> Bu veriye uygun bir metric dashboard tasarla. (attached: `orders_2026.csv` -
+> order_id, user_id, created_at, status, amount, channel)
+
+**Must contain**
+- [ ] Names a North Star and its input metrics as a tree of hypotheses, before any chart
+- [ ] Gives every metric its record: goal, signal, definition (numerator / denominator), window, baseline, direction, leading/lagging, logged yes/no/unknown, and where the data lives (here, which CSV columns)
+- [ ] Turns counts into ratios and marks what the CSV cannot answer (no session or visit column, so no conversion rate) as `logged: no` or `unknown`
+- [ ] Routes the screen itself to `design-contract`'s `data-views.md`: dashboard type, chart per question, the widget states
+
+**Must not**
+- Propose a grid of charts over every column with no goal above each metric
+- Promise a metric the data does not log
+
+**Why this case** - the Metrics section says a metric "is chosen, not collected",
+lists the record fields, and says "A metric marked `logged: no` is instrumented
+before anything is promised on it". A CSV pulls toward charting its columns.
+
+---
+
 ## What these do not prove
 
 These are trap cases for a human or judge rater, not a behavioural measurement.

package/skills/product-analysis/SKILL.md

@@ -39,7 +39,7 @@ of a product nobody can observe is a hypothesis, and it says so.
 
 | Axis | The question | Standard | The hard rule |
 |---|---|---|---|
-| Value (PM) | is it worth building? | HEART and its Goals -> Signals -> Metrics process (Rodden, Hutchinson, Fu, CHI 2010); Opportunity Solution Tree with the opportunity score (Torres; Olsen) | a metric with no goal above it is dropped; raw counts are refused; an opportunity is a need; three solutions compared against a pre-stated criterion |
+| Value (PM) | is it worth building? | HEART and its Goals -> Signals -> Metrics process (Rodden, Hutchinson, Fu, CHI 2010); Opportunity Solution Tree with the opportunity score (Torres; Olsen) | a metric with no goal above it is dropped; raw counts are refused; an opportunity is a need; solutions are compared under `decisions/` when the user chooses between them |
 | Usability (UX) | can a person actually use it? | Nielsen's 10 heuristics with the 0-4 severity scale; the cognitive walkthrough's four questions; WCAG 2.2 AA, and the W3C WCAG2Mobile note for native apps; Apple HIG or Material 3 for platform feel | a UI claim is read from the running app through `analyze-app` - down to component x state, never inferred from source - and the rendered screen is read, not only the tree; severity is frequency x impact x persistence; each finding says whether it is a provable failure (a WCAG criterion) or a judgement, and how many passes produced it |
 | Feasibility (PE) | does it do what it says? | intended vs implemented | a claim is a cited `path:line` or graph symbol; a doc-vs-code gap is a finding only when **both** sides are cited; when the ask is one feature, the layer matrices decide it |
 | Competition | where does it stand, and where can it lead? | a teardown (architecture, features, process, cost/performance, strategic meaning) with the comparison basis stated **before** comparing; review mining (categorise themes, sentiment per theme, compare to us, name gaps) | every competitor fact carries its artifact and the date it was read; a cost or effort number is a range with its assumptions |
@@ -48,6 +48,29 @@ of a product nobody can observe is a hypothesis, and it says so.
 Calibrate to stage before prescribing: telling a pre-launch prototype to fix its
 dependency graph, or a scaling product to "find product-market fit", is malpractice.
 
+## Metrics
+
+A metric is chosen, not collected. Name one North Star - the value users get, an
+outcome nobody moves directly - and the few input metrics believed to drive it, as
+a tree whose every edge is a hypothesis to test, not a fact (Amplitude, *The North
+Star Playbook*). Each metric in the tree is one record:
+
+| Field | What goes in it |
+|---|---|
+| goal | the HEART goal it traces to; no goal, no metric |
+| signal | the behaviour or attitude that shows the goal moving |
+| definition | numerator / denominator: a count becomes a ratio, a percentage or a per-user average (HEART) |
+| window | the period it is computed over |
+| baseline | what it is compared against: a target, the previous period or a benchmark |
+| direction | which way is good |
+| leading/lagging | whether it predicts the outcome or reports it |
+| logged | yes / no / unknown: is the signal recorded today? |
+| where the data lives | the table, event, export or file it is computed from |
+
+A metric marked `logged: no` is instrumented before anything is promised on it, and
+`unknown` is the gate's first finding. A dashboard ask takes this tree as its input
+and then `design-contract`'s `data-views.md` for the screen.
+
 ## When the ask is one feature: run the coherence pass first
 
 A product question about one feature - an admin screen, a CRUD surface, a form, a
@@ -243,17 +266,20 @@ Run it as a research line, not a monologue: `tezgah-research init <slug>
 --question "..."` under the repository's `.tezgah/research/`, then `check` before
 reporting. Declare the line's `deliverable` in `state.json` as `{"kind":
 "analysis", "path": "<where the analysis lands>", "ask": [<the ask's items>]}`, so
-`check` holds it to three compared solutions and to answering every ask item. On
-top of what `check` already enforces, the analysis contains:
+`check` holds it to answering every ask item. An analysis answers its question
+once - `check` asks no variants of it - and a design or plan the user chooses
+between goes under `decisions/` with at least three variants. On top of what
+`check` already enforces, the analysis contains:
 
 1. Measurement readiness: what is observable today, and what is not.
 2. The objective: one measurable outcome and its Goal -> Signal -> Metric chain.
-3. Opportunities with their evidence class; the candidate solutions recorded as
-   `decisions/<id>/` (the research skill's "Variants"): at least three produced
-   solutions plus the status quo as V0, the criterion set committed in
-   `criteria.json` before any solution is scored, every cell appended with
-   `tezgah-research compare` (a judged cell with two raters), and `decision.md`
-   naming the chosen solution, what ruled out each other one and the `flip:`.
+3. Opportunities with their evidence class. When the user is to choose between
+   solutions, they are recorded as `decisions/<id>/` (the research skill's
+   "Variants"): at least three produced solutions plus the status quo as V0, the
+   criterion set committed in `criteria.json` before any solution is scored, every
+   cell appended with `tezgah-research compare` (a judged cell with two raters), and
+   `decision.md` naming the chosen solution, what ruled out each other one and the
+   `flip:`. Otherwise the analysis names the recommended one and why.
 4. Risks by class - value, usability, viability, feasibility - each with the
    cheapest test that would falsify it.
 5. The usability section: scope (task, section, device, breakpoints), the heuristics
@@ -284,6 +310,17 @@ named in the artifact with the reason it was not - an element inside a section,
 only a section: a state matrix left out silently, an image test never run, an
 axe-core sweep dropped or a scorecard dimension missing all read the same way.
 
+## The product flow notes
+
+Under `product-flow`, the axes' findings land in `.tezgah/analysis/<topic>/flow.md`,
+one `## <step>` heading per step. A metric from section 2 goes under `## metrics`
+with its full record and the need it rests on. A risk from section 4 goes under
+`## assumptions` with its kind (a value risk is desirability). A triage row goes
+under `## decision` with its metric, threshold and `observe after: YYYY-MM-DD`,
+the date its timeframe ends. A metric the decision names that is not logged yet
+goes under `## instrumentation` with the event or query that will log it. The
+`product-flow` skill gives the order of the steps.
+
 ## The scorecard
 
 Score each dimension 1-5 and report the mean with its anchors; the anchors are the
@@ -299,8 +336,8 @@ any dimension at 1, reject.
 | Depth | does every screen reach component x state, and is anything measured rather than eyeballed? |
 | Image evidence | were the rendered screens actually read - the blur and grayscale tests, the breakpoints, dark mode - or only the tree? |
 | Axis coverage | are all five axes addressed or explicitly excluded? |
-| Metric integrity | does the metric trace to a goal, and is it a ratio with a definition? |
-| Solution plurality | were at least three solutions compared against a pre-stated criterion? |
+| Metric integrity | does every metric trace to a goal and carry its full record - a ratio with its definition, window, baseline and `logged` answer? |
+| Solution plurality | when the user chooses between solutions, were at least three compared under `decisions/` against criteria committed first? |
 | Feasibility grounding | is the implementation claim a cited code path, not an inference? |
 | Decision quality | does every feature end keep / fix / cut / bet, with a criterion and an owner? |
 | Scope calibration | does the analysis say what it did not look at, and what would flip it? |
@@ -333,6 +370,8 @@ Read the one that matches the axis; never cite these from memory.
 - `phuryn/pm-skills` (MIT) - `pm-data-analytics` (cohort, A/B), `pm-ai-shipping`
   (security and performance audits, test-coverage map), the rest of discovery.
 - HEART, `https://research.google.com/pubs/archive/36299.pdf` (CHI 2010).
+- The North Star and its inputs, leading and lagging: Amplitude, *The North Star
+  Playbook*, `https://amplitude.com/books/north-star/about-the-north-star-framework.md`.
 - Nielsen's 10 heuristics and the severity scale,
   `https://www.nngroup.com/articles/ten-usability-heuristics/` and
   `https://www.nngroup.com/articles/how-to-rate-the-severity-of-usability-problems/`.

package/skills/product-flow/EVALS.md

@@ -0,0 +1,81 @@
+# Evals
+
+Three inputs a session can be handed where this skill could misfire, and what a
+good answer has to contain. Each case is built so a plausible but shallow answer
+fails at least one check.
+
+Run a case by giving the session only the **Input**, with the skill reachable
+from the router. A case passes when every Must-contain line is met and no
+Must-not line is triggered.
+
+---
+
+## Case 1 - The trap: drawing the dashboard before the flow says so
+
+**Input**
+> Bu veriye uygun bir metric dashboard tasarla. (attached: `sales.csv` - date,
+> region, product, orders, revenue, returns)
+
+**Must contain**
+- [ ] Picks one kebab-case topic and runs `tezgah-research next --topic <t>` before any layout, and does the first missing step it names
+- [ ] Writes each step's note under its `## <step>` heading in `.tezgah/analysis/<t>/flow.md`, each naming the note it rests on
+- [ ] Takes the metrics from `## metrics` notes that rest on a need under `## research` (goal, signal, definition, window, baseline, logged), written before the design step
+- [ ] Gives the decision under `## decision` a metric, a threshold and an `observe after: YYYY-MM-DD` date
+- [ ] Names that decision in `.tezgah/analysis/<t>/spec.md` and in the design-contract component
+
+**Must not**
+- Lay out charts for the CSV's columns before a metric and a decision exist
+- Skip a step whose artifact is missing because the data seems to answer it
+
+**Why this case** - the skill says to "find the first step whose artifact is
+missing" and do "that step, and only that step". A data file pulls toward drawing
+its columns at once.
+
+---
+
+## Case 2 - The trap: a research worker writing the flow's artifacts
+
+**Input**
+> We want to add saved searches to the app. Spin up research on how users
+> re-run searches and take it from there.
+
+**Must contain**
+- [ ] Runs `tezgah-research next --topic <t> --flow feature` (no metric is in view) and starts from the first missing step
+- [ ] Briefs any research worker to report its sources and insights - class, source with its read date, quote, statement, confidence - in its result
+- [ ] Writes those findings under `## research` in `flow.md` from the main session
+
+**Must not**
+- Let a worker or subagent write `flow.md` or `spec.md` itself
+- Start the forward spec before `## decision` exists
+
+**Why this case** - "Who writes" says "Only the main session writes the flow's
+artifacts". A delegated research step pulls toward letting the worker write its
+own findings.
+
+---
+
+## Case 3 - The trap: "just build the chart"
+
+**Input**
+> Skip the process, just build the chart of weekly revenue. No need for metrics
+> or goals.
+
+**Must contain**
+- [ ] Runs `next` for the topic and states which steps are missing before the build, naming the metric and the decision
+- [ ] Says the chart has no goal above it, and asks for the goal or writes the gap down as a step still missing
+- [ ] Offers the shortest route through the missing steps, one note each, rather than refusing
+
+**Must not**
+- Build the chart and report the flow as done
+- Claim the metric or decision steps do not apply to this ask
+
+**Why this case** - every step's artifact "names the earlier artifact it rests
+on": a built chart with no metric and no decision leaves the earlier steps missing
+however good the chart is.
+
+---
+
+## What these do not prove
+
+These are trap cases for a human or judge rater, not a behavioural measurement.
+`skills/research` owns the standard a claim about behaviour has to meet.

package/skills/product-flow/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: product-flow
+description: >
+  Carries a new product capability from evidence to a measured result: it walks
+  the nine steps of the flow in order - research, metrics, assumptions,
+  decision, instrumentation, forward spec, design, build, re-measure - and does
+  the first step whose artifact is missing with the skill that step names, so
+  each hand-off is a written artifact that names the one before it instead of a
+  memory. Use when a session must design a metric dashboard, a new metric or a
+  new feature from data or an ask, and carry it from research to re-measure. Not
+  for auditing an existing feature - use `feature-audit`.
+---
+
+# product-flow
+
+A new product capability - a dashboard over a data file, a metric, a feature
+someone asked for - drifts when its steps live in the session's head: the chart
+gets drawn before anyone says which goal it serves, and nobody comes back to see
+whether the decision held. This skill keeps the sequence written down: the steps
+below, in order, each leaving an artifact on disk that names the artifact it
+rests on.
+
+## When to use it
+
+- A new capability from data: "bu veriye uygun metric dashboard tasarla", a CSV or
+  export with "what should we track".
+- A new capability from an ask: "add a feature that ...", "we need a metric for ...".
+- A topic already in progress, to see what is left of it.
+
+Not for an existing feature's audit (`feature-audit`), and not for a product-wide
+analysis with no new capability in view (`product-analysis`). Both are steps this
+flow can hand off to.
+
+## The steps
+
+Pick one kebab-case topic for the capability, such as `signup-dashboard`. Every
+artifact of this capability lives under `.tezgah/analysis/<topic>/`: the notes of
+steps 1-5 and 9 in `flow.md`, one `## <step>` heading per step, and the forward
+spec in `spec.md`. Each step's artifact names the earlier artifact it rests on.
+
+1. **research** (`research` skill). At least one external source - its URL or
+   title, the date it was read and the passage it says - and the user need or
+   insight that source supports.
+2. **metrics** (`product-analysis`). Each metric rests on a need from step 1 and
+   states its goal, signal, definition, window, baseline, and whether it is
+   logged today.
+3. **assumptions** (`product-analysis`). The assumptions the decision will rest
+   on, each one a sentence that could turn out false.
+4. **decision** (`product-analysis`). A decision that names one of the topic's
+   metrics, the threshold that would change it, and the date after which it is
+   re-measured (observe after).
+5. **instrumentation** (`product-analysis`). Every metric the decision names is
+   logged; a metric that is not logged yet gets the event or query that will log
+   it.
+6. **forward-spec** (`feature-audit`, forward mode). `.tezgah/analysis/<topic>/spec.md`,
+   naming the decision it implements.
+7. **design** (`design-contract`). A component in `.tezgah/design-contract.md`
+   that names the decision it serves.
+8. **build** (`design-contract`). Judged by the design check
+   (`tezgah-design check`) and the Stop UI rule, not by this flow.
+9. **re-measure** (`analyze-app`). Once the decision's observe-after date has
+   passed, measure the decision's metric again and write the result and what it
+   means for the decision.
+
+A feature ask that names no metric skips steps 2 and 5, unless the topic already
+holds a metric.
+
+## The loop
+
+The step source is `~/.config/tezgah/bin/tezgah-research next --topic <t>` (`--flow feature` for a feature ask): a step is done once `flow.md` holds its `## <step>` heading (design and build too) or, for the forward spec, once `spec.md` exists, and the re-measure is due once the decision's `observe after: YYYY-MM-DD` has passed.
+
+1. Read what already exists under `.tezgah/analysis/<topic>/` and find the first
+   step whose artifact is missing, or the re-measure whose date has passed.
+2. Do that step, and only that step, with the skill it names. Read that skill; it
+   says what the step's artifact holds.
+3. Write the artifact, naming the artifact it rests on.
+4. Go back to 1. Stop when every step's artifact exists, or when the only step
+   left is a re-measure whose date has not come yet.
+
+## Who writes
+
+Only the main session writes the flow's artifacts. A research worker, a subagent
+or a specialist reports its sources and insights - the class, the source with the
+date it was read, the quote, the statement and its confidence - in its result, and
+the main session writes them down.
+
+## What this skill does not do
+
+It does not decide what a metric is, how a dashboard looks or what a feature spec
+holds: the skill each step names owns that (`product-analysis`, `research`,
+`feature-audit`, `design-contract`, `analyze-app`).

package/skills/research/SKILL.md

@@ -69,7 +69,8 @@ breaking one silently invalidates the run:
 Load its manual before driving it: `orx skill`, then the module for the step
 (`orx skill lit-review` for sources; `orx skill experiment-tree` and
 `orx skill evidence` for a measured line).
-Local runs need no login; managed compute does - ask the user to run `orx login`.
+Local runs need no login; managed compute does - run locally at a scale that fits,
+and ask for `orx login` only when the question cannot be answered without it.
 If `orx` is absent, say the research tooling is unavailable and do not improvise
 its protocol; the workspace below still applies to whatever you run instead.
 
@@ -578,6 +579,14 @@ palette rather than the default cycle; and size for the venue's column width whe
 the figure is headed into a paper. The library's `index/6-write.md` entries carry
 the full rules when a line reaches that stage.
 
+## A source that answers a product ask
+
+When a line's source answers a product question under `product-flow`, the finding
+also goes under `## research` in `.tezgah/analysis/<topic>/flow.md`: the source's
+URL or literature path, the date it was read and the passage it says, then the
+user need it supports. A research claim it rests on is cited as
+`<slug>:<claim id>`. The `product-flow` skill gives the order of the steps.
+
 ## Provenance, at the end of the session
 
 Research is a sequence of decisions, and the next session does not remember them.