@r1z4x/tezgah 1.5.1 → 1.7.0

package/skills/design-contract/data-views.md

@@ -0,0 +1,86 @@
+# Data views
+
+The rules a dashboard, a chart or a metric tile is held to, on top of the state set
+in `SKILL.md`. The metrics themselves - which ones, their definition, window,
+baseline and whether they are logged - come from `product-analysis`'s Metrics
+section; this file decides how they are shown. Each rule names its source, and a
+rule with no primary source found says so.
+
+## The dashboard type comes first
+
+Decide whether the screen is **operational** - critical information read quickly
+during a time-sensitive task - or **analytical** - at-a-glance information for
+analysis and decision making (NN/g). Carbon draws the same line as presentation
+against exploration dashboards. The type sets the density, the refresh rate and
+how much interaction the screen owes; a dashboard that has not named its type has
+not named its user.
+
+## Chart choice follows the question
+
+Name the question each view answers, then pick the encoding:
+
+| The question | Encoding | Source |
+|---|---|---|
+| comparison - which is bigger? | bars on a common baseline | NN/g (length on a common scale) |
+| trend - how did it move over time? | a line over a time axis | NN/g (position) |
+| part-to-whole - what share is each? | a stacked bar, or a bar of shares | tezgah's own: no primary source read |
+| distribution - how is it spread? | a histogram or a box plot | tezgah's own: no primary source read |
+| relationship - does one move with another? | a scatter plot | NN/g (position on two axes) |
+
+Length and position carry quantity, because people compare them accurately; area
+and angle (pie, gauge, radar) do not (NN/g, after Cleveland and McGill). Colour
+never encodes a magnitude: it is a redundant grouping cue beside a label, a shape
+or a position, and every chart passes the greyscale test - it still reads with the
+colour removed (NN/g; the design library's `colour-independence` entry).
+
+## Every number has context and a window
+
+A bare number cannot be judged: "Compared to what? Is this good or bad?" (Few,
+*Common Pitfalls in Dashboard Design*). Every figure shown carries its comparison
+- a target, the previous period or a benchmark - and the window it covers, and is
+formatted with its unit and no more precision than the decision needs (Few's
+"excessive detail or precision" pitfall). The record behind each comes from the
+metric's `baseline` and `window` fields.
+
+## Three to five metrics by default
+
+The default view shows 3-5 key metrics and the primary actions; the rest sit
+behind a fuller view the user opens (the design library's `simplified-views`
+entry). Carbon's "Limit the number of metrics" and Few's "exceeding the
+boundaries of a single screen" say the same. The most important metric gets the
+largest area and the highest contrast (Carbon).
+
+## The widget state set
+
+Every widget - tile, chart, table - owes each of these states, and a state that
+does not exist is a finding:
+
+| State | What it shows | Source |
+|---|---|---|
+| loading | that data is on the way, in the widget's own frame | Carbon's loading pattern, seen but not read at source |
+| no-data | that the query returned nothing, and what would fill it | Carbon empty states |
+| error | that the system failed, per widget, with a text-only message when many fail | Carbon empty states ("Systems issue") |
+| permission-denied | that data exists but this user may not see it | Carbon empty states ("Permissions issue") |
+| configuration-needed | that the widget cannot run until something is set up | Carbon empty states ("Configuration required") |
+| stale | the last good data, with its "as of" time | tezgah's own rule: no primary source found |
+| partial | which part of the data is missing, beside what arrived | tezgah's own rule: no primary source found |
+
+Against the contract: loading, error, partial and permission-denied are already in
+`states.data`, and no-data is its `empty`; configuration-needed and stale are
+reported as observed state names beside the shipped set, and their absence is a
+finding the reviewer names, since `check` does not require them.
+
+## Sources
+
+- Stephen Few, *Common Pitfalls in Dashboard Design* (2006),
+  http://www.perceptualedge.com/articles/Whitepapers/Common_Pitfalls.pdf
+- NN/g, *Dashboards: Making Charts and Graphs Easier to Understand* (2017),
+  https://www.nngroup.com/articles/dashboards-preattentive/
+- Carbon Design System, Dashboards,
+  https://www.carbondesignsystem.com/data-visualization/dashboards
+- Carbon Design System, Empty states,
+  https://www.carbondesignsystem.com/building-blocks/core/patterns/empty-states
+- The design library: [colour-independence](../design-library/adaptive-interfaces/skills/colour-independence/SKILL.md)
+  ("Always test charts in greyscale") and
+  [simplified-views](../design-library/adaptive-interfaces/skills/simplified-views/SKILL.md)
+  (its Dashboard Simplification patterns: a default of three to five key metrics).

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/i-have-adhd/EVALS.md

@@ -1,6 +1,6 @@
 # Evals
 
-Three inputs a session can be handed where this skill could misfire, and what a
+Four 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.
 
@@ -41,7 +41,7 @@ long as the topic needs". The user states that completeness is the point.
 **Must contain**
 - [ ] States the location (the connection to `10.0.4.12:5432`) and what is known from the line
 - [ ] Separates what the line shows (a timeout to the database port) from guesses about why
-- [ ] Names the one check that would confirm the leading guess, as the next action
+- [ ] Runs the check that would confirm the leading guess when this machine can reach the host; when it cannot, names that check as the one step the reader takes, with the attempt and its error
 
 **Must not**
 - State a single root cause (firewall, wrong password, database down) as fact
@@ -74,6 +74,26 @@ needs". The output-shaping rules would otherwise delete the answer.
 
 ---
 
+## Case 4 - The trap: a next step the session can take itself
+
+**Input**
+> Fix the off-by-one in the pagination helper and tell me when it is ready.
+
+**Must contain**
+- [ ] Fixes the off-by-one and runs the helper's test itself, reporting its output
+- [ ] Ends on what now works, or on ONE step only the reader can take (a decision, a grant, a consent)
+
+**Must not**
+- End with "Next: run `npm test`" or any other step the session could run itself
+- End on a "Sıradaki adım" list
+
+**Why this case** - Rule 4 reads "End with the one step that is the reader's to
+take": "A step you can take yourself is not a next step: take it." Running the
+test is the session's own step, and "tell me when it is ready" invites handing it
+over.
+
+---
+
 ## What these do not prove
 
 These are trap cases for a human or judge rater, not a behavioural measurement.

package/skills/i-have-adhd/SKILL.md

@@ -85,13 +85,19 @@ restating. Never also narrate the plan as prose: two copies of the same state is
 the ceremony this rule exists to remove, and it is the one place where this rule
 would otherwise fight the exec contract's ban on summaries.
 
-### 4. End with one concrete next step
+### 4. End with the one step that is the reader's to take
 
-If anything is open, name ONE thing the reader can do, small enough to start
-now. "Open the file" counts.
+If something is left that only the reader can do - a decision, a credential or
+grant, consent for a step that cannot be undone - name that ONE step, small
+enough to start now. Several such decisions go in one numbered approval batch,
+each with a recommended default, and the work proceeds on the defaults (the
+tezgah contract's Ask policy). A step you can take yourself is not a next step:
+take it, and never end on asking whether to. When nothing is left, end on what
+now works.
 
 Bad: "Hope that helps. Let me know if you want to dig deeper."
-Good: "Next: run `npm test` and paste the first failing line."
+Bad: "Next: run `npm test` and paste the first failing line." (you can run it)
+Good: "Blockers: the push to `main` - IRREVERSIBLE - `git push origin main` waits - your yes." (tr: "Engeller", GERİ ALINAMAZ)
 
 ### 5. Suppress tangents
 
@@ -121,7 +127,8 @@ worse than a named unknown.
 
 Say what now works, not what was touched. "Login works with magic links; try
 `npm run dev` and open `/login`." A claim about what works is still a claim: it
-carries the evidence that was actually observed, or it is marked unverified.
+carries the evidence that was actually observed. Try the check first; a claim is
+marked unverified only after that check ran and failed, with the failure quoted.
 
 ### 8. Cap a list at five items
 

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,30 @@ 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 record:
+   the gate refuses a write to it, because the CLI's checks would be skipped.
+   Tick an Acceptance box with `tezgah-task tick NNN <n>` (`--undo` unticks),
+   and rewrite State or Next with `tezgah-task note NNN state|next "<text>"`.
+   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 +134,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,23 @@ 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.
+   round two; a minor or suggestion one is fixed in the session without a new
+   round, or recorded fix-later only when it waits on a user decision (DECISION,
+   tr: KARAR); after round two what is left is fixed by the session and closed
+   with `--resolved`, or recorded fix-later only with DECISION (tr: KARAR),
+   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 +71,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/ponytail/EVALS.md

@@ -1,6 +1,6 @@
 # Evals
 
-Three inputs a session can be handed where this skill could misfire, and what a
+Four 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.
 
@@ -41,7 +41,7 @@ all callers route through".
 **Must contain**
 - [ ] Keeps a check that the filename cannot escape `uploads/` (path traversal)
 - [ ] Keeps the rest of the handler short, with stdlib calls only
-- [ ] States in at most three lines what was skipped and why the path check stayed
+- [ ] States in at most three lines that the path check stayed against the request, and why
 
 **Must not**
 - Write the posted filename straight into the path with no check
@@ -74,6 +74,25 @@ the prompt is a trigger phrase that points the wrong way.
 
 ---
 
+## Case 4 - The trap: a skipped-items note nobody asked for
+
+**Input**
+> Add caching to fetch_rates(); keep it minimal.
+
+**Must contain**
+- [ ] A stdlib cache (`functools.lru_cache` or equal) on `fetch_rates` and one runnable check
+- [ ] No note line after the code, since nothing the user asked for was cut
+
+**Must not**
+- A "Skipped: TTL, eviction, add when ..." line
+- A "Next steps" or "İleride eklenebilir" list
+
+**Why this case** - the Output section says "Write what was cut only when you
+consciously cut something the user asked for"; a TTL or an eviction policy was
+never asked for, so listing it is a residual, not a cut.
+
+---
+
 ## What these do not prove
 
 These are trap cases for a human or judge rater, not a behavioural measurement.

package/skills/ponytail/SKILL.md

@@ -39,7 +39,7 @@ table below, so the turn carries the semantics and not only the word.
 
 Stop at the first rung that holds:
 
-1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
+1. **Does this need to exist at all?** Speculative need = skip it, with no note: nothing the user asked for was cut. (YAGNI)
 2. **Already in this codebase?** A helper, util, type, or pattern that already lives here → reuse it. Look before you write; re-implementing what's a few files over is the most common slop.
 3. **Stdlib does it?** Use it.
 4. **Native platform feature covers it?** `<input type="date">` over a picker lib, CSS over JS, DB constraint over app code.
@@ -71,14 +71,14 @@ every sibling caller still broken. Fix it once, where all callers route through.
 
 ## Output
 
-Code first. Then at most three short lines: what was skipped, when to add it. This section is the whole of what ponytail says about the reply's shape; how the reply reads otherwise - the answer first, at most five ranked items, no preamble - is `i-have-adhd`'s, and the exec contract owns the language.
+Code first. Write what was cut only when you consciously cut something the user asked for, in at most three short lines; anything else you can do is done, not listed. This section is the whole of what ponytail says about the reply's shape; how the reply reads otherwise - the answer first, at most five ranked items, no preamble - is `i-have-adhd`'s, and the exec contract owns the language.
 No essays, no feature tours, no design notes. If the explanation is longer
 than the code, delete the explanation, every paragraph defending a
 simplification is complexity smuggled back in as prose. Explanation the user
 explicitly asked for (a report, a walkthrough, per-phase notes) is not debt,
 give it in full, the rule is only against unrequested prose.
 
-Pattern: `[code] → skipped: [X], add when [Y].`
+Pattern, only for a requested part you cut: `[code] → cut: [X the user asked for], because [Y].`
 
 ## Intensity
 
@@ -90,7 +90,7 @@ Pattern: `[code] → skipped: [X], add when [Y].`
 
 Example: "Add a cache for these API responses."
 - lite: "Done, cache added. FYI: `functools.lru_cache` covers this in one line if you'd rather not own a cache class."
-- full: "`@lru_cache(maxsize=1000)` on the fetch function. Skipped custom cache class, add when lru_cache measurably falls short."
+- full: "`@lru_cache(maxsize=1000)` on the fetch function."
 - ultra: "No cache until a profiler says so. When it does: `@lru_cache`. A hand-rolled TTL cache class is a bug farm with a hit rate."
 
 ## When NOT to be lazy

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/`.