narrativetrace 0.2.0__tar.gz → 0.3.0__tar.gz

{narrativetrace-0.2.0 → narrativetrace-0.3.0}/LICENSE

@@ -7,7 +7,7 @@ Parameters
 
 Licensor:             Empower Agile
 
-Licensed Work:        NarrativeTrace for Python (the narrativetrace PyPI distributions) version 0.2.0. The Licensed Work is (c) 2026 Empower Agile.
+Licensed Work:        NarrativeTrace for Python (the narrativetrace PyPI distributions) version 0.3.0. The Licensed Work is (c) 2026 Empower Agile.
 
 Additional Use Grant: You may make production use of the Licensed Work for any
                       purpose, including internal use and use in products and
@@ -18,7 +18,7 @@ Additional Use Grant: You may make production use of the Licensed Work for any
                       parties as a logging, tracing, or code-narrative product
                       or service.
 
-Change Date:          Four years from the date the Licensed Work is published. (2030-10-05 for this version)
+Change Date:          Four years from the date the Licensed Work is published. (2030-10-10 for this version)
 
 Change License:       Apache License, Version 2.0
 

{narrativetrace-0.2.0 → narrativetrace-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: narrativetrace
-Version: 0.2.0
+Version: 0.3.0
 Summary: Narrative execution tracing for Python — human- and LLM-readable traces
 Project-URL: Homepage, https://github.com/narrativetrace/narrativetrace-python
 Project-URL: Source, https://github.com/narrativetrace/narrativetrace-python

{narrativetrace-0.2.0 → narrativetrace-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "narrativetrace"
-version = "0.2.0"
+version = "0.3.0"
 description = "Narrative execution tracing for Python — human- and LLM-readable traces"
 readme = "README.md"
 requires-python = ">=3.12"

{narrativetrace-0.2.0 → narrativetrace-0.3.0}/src/narrativetrace/__init__.py

@@ -97,7 +97,7 @@ from narrativetrace.values import (
     StringVal,
 )
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
     "NOOP_CONTEXT",

{narrativetrace-0.2.0 → narrativetrace-0.3.0}/src/narrativetrace/_skills/agents/add-narrative-tracing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-narrative-tracing
-description: "Installs NarrativeTrace into a Python project and gets it to a first trace. Use when NarrativeTrace is not yet installed, a project needs its very first traced call, or traces need to reach a real logger instead of bare print statements. Installs narrativetrace with uv add, wraps an object with trace_object, renders and runs the first trace, then wires the stdlib logging bridge so traces reach your logger. Runs narrativetrace doctor to confirm the install is correctly wired -- narrativetrace-doctor owns diagnosis from there -- and previews the agent-skills install so the next session finds them. Say 'add narrative tracing to my service', 'install narrativetrace', 'get a trace in 60 seconds', 'wrap this object so I can see a trace', or 'send my traces to my logger' to invoke it."
+description: "Installs NarrativeTrace into a Python project and gets it to a first trace. Use when NarrativeTrace is not yet installed, a project needs its very first traced call, or traces need to reach a real logger instead of bare print statements. Installs narrativetrace with uv add, wraps an object with trace_object, renders and runs the first trace, then wires the stdlib logging bridge so traces reach your logger. Applies the doctor's framework-wiring fixes for the frameworks the project already uses, and runs narrativetrace doctor to confirm the install is correctly wired -- narrativetrace-doctor owns diagnosis from there -- and previews the agent-skills install so the next session finds them. Say 'add narrative tracing to my service', 'install narrativetrace', 'get a trace in 60 seconds', 'wrap this object so I can see a trace', or 'send my traces to my logger' to invoke it."
 ---
 
 # add-narrative-tracing
@@ -21,7 +21,27 @@ sys.exit(1 if bad else 0)
 
 **failure:** a sibling narrativetrace-* package disagrees on version — an installed distribution outside the lockstep version the other narrativetrace-* packages share. Fix: run the narrativetrace-doctor skill's toolchain.package-versions check, then pin every narrativetrace-* dependency to the same version and `uv sync`
 
-## 2. First trace: wrap, call, render, run
+## 2. Wire the frameworks this project already uses
+
+```bash
+uv run narrativetrace doctor || true
+```
+
+**verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
+from narrativetrace_tooling.frameworks.table import wiring_check_ids
+report = json.load(sys.stdin)
+ids = set(wiring_check_ids())
+bad = [f for f in report["findings"] if f["id"] in ids and f["status"] != "pass"]
+for f in bad:
+    print(f["id"] + ": " + f["fix"])
+sys.exit(1 if bad else 0)
+'`
+
+**failure:** a config.<framework>-* finding fails — the doctor detected a framework this project uses whose NarrativeTrace integration is not added, or is added but never wired. Fix: run the doctor; apply every config.<framework>-* fix it prints, in order; a framework it reports as having no integration shipped is left alone
+
+## 3. First trace: wrap, call, render, run
+
+**when:** if the project already has an application entry point — a script or module that starts it, a web or application framework the doctor reports — do not create a demo main.py: run the application the way it already runs, exercise one real boundary, and read that request's trace; the verify below is for the standalone script, and in an existing application the step is done when that request's trace is in the output; otherwise create the smallest script as follows
 
 <!-- snippet: examples/sixty_seconds/main.py -->
 ```python
@@ -56,7 +76,9 @@ print(IndentedTextRenderer().render(context.capture_trace()))
 
 **failure:** a *args method's parameters render as one args: [...] value — inspect.signature has nothing named to reconstruct per-argument that Python itself does not have. Fix: supply explicit names: @traced("first", "second", ...) above the method
 
-## 3. Send it to your logger
+## 4. Send it to your logger
+
+**when:** if the project already has an application entry point — a script or module that starts it, a web or application framework the doctor reports — do not create a second main.py or a second logging setup: add the filter and the export_to_logger call to the application's own logging configuration and the boundary you exercised; the verify below is for the standalone script, and in an existing application the step is done when that boundary's trace reaches the application's own logger; otherwise create the smallest script as follows
 
 <!-- snippet: examples/sixty_seconds/main_with_logger.py -->
 ```python
@@ -110,7 +132,7 @@ export_to_logger(trace)  # new: sends the same captured trace through the config
 
 **verify:** `uv run python main_with_logger.py`
 
-## 4. Run the doctor and resolve its findings
+## 5. Run the doctor and resolve its findings
 
 ```bash
 uv run narrativetrace doctor || true
@@ -119,15 +141,17 @@ uv run narrativetrace doctor || true
 **verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
 report = json.load(sys.stdin)
 findings = report.get("findings")
-sys.exit(1 if not isinstance(findings, list) or len(findings) != 12 else 0)
+sys.exit(1 if not isinstance(findings, list) or len(findings) != 19 else 0)
 '`
 
-## 5. Install the skills for next time
+## 6. Install the skills for next time
 
 ```bash
 uv run narrativetrace init --dry-run
 ```
 
+**done when:** the preview wrote nothing; the next session verifies with narrativetrace-verify — once a change's tests are green, it reads the trace before it reports
+
 **verify:** `uv run python -c 'import pathlib, subprocess, sys
 result = subprocess.run(
     ["uv", "run", "narrativetrace", "init", "--dry-run"], capture_output=True, text=True
@@ -150,5 +174,5 @@ sys.exit(0 if result.returncode == 0 and shown and untouched else 1)
 ## Never
 
 - Never assume a step worked without running its verify. (self-reported success overstates reality -- a build claimed green that does not reproduce from clean is not evidence)
-- Never skip the final narrativetrace doctor call. (it is the seam that catches anything these four steps did not -- narrativetrace-doctor owns diagnosis from here)
+- Never skip the final narrativetrace doctor call. (it is the seam that catches anything these five steps did not -- narrativetrace-doctor owns diagnosis from here)
 - Never apply the installer without showing its diff first. (it writes into AGENTS.md and the project's skill directories, and the approval for that is a person reading the diff -- run it with --dry-run, show the output, and let them run it again without the flag)

narrativetrace-0.3.0/src/narrativetrace/_skills/agents/add-narrativetrace-clarity/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: add-narrativetrace-clarity
+description: "Adds or verifies NarrativeTrace Clarity in a Python project. Use when you want a first naming report, per-element suggestions, or an explicit clarity quality gate. Installs narrativetrace-clarity with uv add --dev, runs the real narrativetrace-clarity scan over the project's packages, checks the report is fresh and scored at least one class, renames what it flags, and re-runs until the gate is clean, preserving any thresholds the project already has. Route tracing itself being broken to narrativetrace-doctor. Say 'add a clarity report to this project', 'run narrativetrace-clarity', 'explain our clarity scores', 'make the clarity gate fail on low scores', or 'which names make this hard to read' to invoke it."
+---
+
+# add-narrativetrace-clarity
+
+## 1. Find what to scan and what is already there
+
+```bash
+git ls-files '*.py' 'pyproject.toml'
+```
+
+**verify:** `git ls-files '*.py' 'pyproject.toml' | uv run python -c 'import sys
+sys.exit(0 if sys.stdin.read().split() else 1)
+'`
+
+**failure:** the listing is empty — this is not a git checkout, or it tracks no Python. Fix: run from the repository root; with no Python to read there is nothing for clarity to score
+
+## 2. Install the gate as a development dependency
+
+```bash
+uv add --dev narrativetrace-clarity
+```
+
+**verify:** `uv run narrativetrace-clarity --help`
+
+**failure:** the console script is not found — the dev dependency was added but the environment was not synced. Fix: run `uv sync`, then run the check again
+
+## 3. Scan the packages and check the report is real
+
+```bash
+uv run narrativetrace-clarity <source-dir> --output-dir build/narrativetrace
+```
+
+**verify:** `uv run python -c 'import json, pathlib, sys, time
+root = pathlib.Path("build/narrativetrace")
+results = root / "clarity-results.json"
+report = root / ("clarity-report" + ".md")
+if not results.is_file() or not report.is_file() or not report.stat().st_size:
+    sys.exit("no report: the scan wrote nothing (wrong source directory?)")
+if time.time() - min(results.stat().st_mtime, report.stat().st_mtime) > 600:
+    sys.exit("stale report: it is from an earlier run, not this scan")
+try:
+    scenarios = json.loads(results.read_text(encoding="utf-8")).get("scenarios")
+except (ValueError, AttributeError):
+    sys.exit("the results file is not a clarity report")
+if not isinstance(scenarios, list) or not scenarios:
+    sys.exit("the report scored no class")
+'`
+
+**failure:** the scan prints `No classes found` and the check says no report — the directory holds no public class: the scan scores classes, skips names with a leading underscore, and does not score module-level functions. Fix: point it at the package directory that holds the project's classes
+
+**failure:** the scores describe libraries, not the project — the scan walked the project root and so the virtual environment under it. Fix: pass the package directories, never `.`
+
+## 4. Read the report and rename what it flags
+
+**failure:** a flagged name is a domain word the project chose on purpose — the scan scores against its built-in dictionaries unless a glossary is committed. Fix: leave the name and say why; the glossary rule below is the lasting fix
+
+**failure:** a flagged method or parameter is part of a public API — renaming it breaks callers outside this repository. Fix: ask before renaming it, and keep the old name as a deprecated alias if so
+
+## 5. Run the project's tests after the renames
+
+**verify:** `uv run pytest -q`
+
+**failure:** a test fails with a name that no longer exists — a caller, a keyword argument or a string still uses the old name. Fix: search the whole repository for the old name and move every use
+
+## 6. Re-run the gate until it is clean
+
+```bash
+uv run narrativetrace-clarity <source-dir> --output-dir build/narrativetrace --min-score <min-score> --max-high-issues <max-high-issues>
+```
+
+**verify:** `uv run python -c 'import json, pathlib, sys, time
+root = pathlib.Path("build/narrativetrace")
+results = root / "clarity-results.json"
+report = root / ("clarity-report" + ".md")
+if not results.is_file() or not report.is_file() or not report.stat().st_size:
+    sys.exit("no report: the scan wrote nothing (wrong source directory?)")
+if time.time() - min(results.stat().st_mtime, report.stat().st_mtime) > 600:
+    sys.exit("stale report: it is from an earlier run, not this scan")
+try:
+    scenarios = json.loads(results.read_text(encoding="utf-8")).get("scenarios")
+except (ValueError, AttributeError):
+    sys.exit("the results file is not a clarity report")
+if not isinstance(scenarios, list) or not scenarios:
+    sys.exit("the report scored no class")
+'`
+
+**failure:** exit 1 naming a class below --min-score, or HIGH issues over the limit — a flagged name is still unclear, or a rename introduced another. Fix: read the new report, rename again, and repeat from the tests
+
+## Always
+
+- Rename in snake_case, whatever case the suggestion's examples use. (the suggestion text shares its wording with the other runtimes, so its examples are camelCase; the idea is the lesson, not the spelling)
+- Read both artefacts of every run, not only the exit code. (a scan that found no class exits 0 and leaves the last run's files in place)
+- Use the thresholds the project already has, and ask before choosing new ones. (enforcement is a decision the project makes, not a default the skill invents)
+- With no thresholds in the project and none requested, re-run the plain scan and report what is left. (a gate nobody asked for fails a build nobody expected to fail)
+- When the project commits a glossary and has narrativetrace-glossary, run the scan through `python -m narrativetrace_glossary.clarity_scan` with the same arguments. (that is the gate that reads the committed vocabulary, so a domain word the project chose on purpose is not flagged as unclear)
+
+## Never
+
+- Never lower or replace a threshold to hide a failure. (a failing gate is evidence about the names; removing the evidence fixes nothing)
+- Never call a scan that found nothing a pass. (an exit 0 with no scored class means the wrong directory was scanned, not that the names are clear)
+- Never add --warn-only to make the gate go green. (an advisory gate exits 0 whatever it found, so green then proves nothing)
+- Never harvest a glossary only to read the existing vocabulary. (the scan reads a committed glossary; creating one is a separate decision that writes to the project)
+- Never promise the score a rename will earn. (a rename's score is measured by the next run, and the report may flag more)

narrativetrace-0.3.0/src/narrativetrace/_skills/agents/narrativetrace-debug/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: narrativetrace-debug
+description: "Finds the cause of a wrong result in a Python project by reading what the code did with the values, not by stepping through it. Use when a symptom is reported -- a wrong amount, a wrong id, a call in the wrong order, a test that fails with a value nobody expected. Reproduces it with the smallest input and NarrativeTrace on, finds the first span where a value diverges and names it by its span id (the sequence diagram first when threads or tasks are involved), narrows to that span's sub-tree, fixes it there and checks the structural trace shows nothing else moved, pins the reproduction as a regression test and an approval baseline behind your yes, and reports the root cause by span id. Hands a defect in NarrativeTrace itself to narrativetrace-feedback. Say 'debug this with the trace', 'find where this value goes wrong', or 'why is this result wrong' to invoke it."
+---
+
+# narrativetrace-debug
+
+## 1. Reproduce the symptom with tracing on
+
+**when:** a test already drives the path with the input from the symptom, run that one; otherwise write the smallest one, as below — the reported input, through the real collaborators each wrapped with trace_object and the narrative_trace fixture, asserting the value the symptom says should have come out
+
+<!-- snippet: examples/sixty_seconds/test_place_order_flow.py -->
+```python
+"""The smallest test that drives a real path through its collaborators, traced: the
+``narrative_trace`` fixture is the capture, and every collaborator on the path is wrapped with it.
+After a run, ``narrative-traces/structural/<module>/<test>.nt`` holds the flow's shape and
+``narrative-traces/traces/<module>/<test>.md`` its values."""
+
+from narrativetrace import ContextVarNarrativeContext, trace_object
+
+
+class Inventory:
+    def reserve(self, product_id: str, quantity: int) -> str:
+        return f"R-{product_id}-{quantity}"
+
+
+class OrderService:
+    def __init__(self, inventory: Inventory) -> None:
+        self._inventory = inventory
+
+    def place_order(self, customer_id: str, product_id: str, quantity: int) -> str:
+        reservation = self._inventory.reserve(product_id, quantity)
+        return f"ORD-{customer_id}-{reservation}"
+
+
+def test_customer_places_an_order(narrative_trace: ContextVarNarrativeContext) -> None:
+    inventory = trace_object(Inventory(), narrative_trace)
+    service = trace_object(OrderService(inventory), narrative_trace)
+
+    assert service.place_order("cust-1", "prod-42", 3) == "ORD-cust-1-R-prod-42-3"
+```
+<!-- /snippet -->
+
+**done when:** the test ran with the reported input, and its .md narrative was written by this run
+
+**verify:** `uv run pytest <the test that reproduces the symptom>`
+
+**failure:** no .md for the test appears under narrative-traces/traces — the test does not request the narrative_trace fixture, the collaborators on the path are not wrapped with it, or the pytest plugin is not registered. Fix: run narrativetrace-doctor and apply its fix, then run the test again
+
+## 2. Find the symptom in the values
+
+```bash
+uv run python -c 'import pathlib; print(*sorted(pathlib.Path("narrative-traces/traces").rglob("*.md")), sep="\n")'
+```
+
+**done when:** the reported value is in this run's .md narrative, or the reproducing test fails on it — a symptom that does not reproduce is said so, and the loop stops here
+
+## 3. Across threads, read the sequence diagram first
+
+**when:** only when the path crosses threads or tasks — the .nt shows a fork, async or fire-and-forget marker — or the symptom is about order (a call that ran before or after another); otherwise go straight to localizing
+
+```bash
+uv run python -c 'import pathlib; print(*sorted(pathlib.Path("narrative-traces/diagrams").rglob("*.mmd")), sep="\n")'
+```
+
+**done when:** the reproduction's .mmd was read before any span's values, and the reply says which call ran before which across the threads, by the span id in each call's note — the span it points to is the one localized next
+
+## 4. Localize by reading: name the first span where a value diverges
+
+**done when:** the reproduction's .md spans were read from the root down until the first one whose inputs are what the symptom implies but whose result, the value it passes on, or the branch it takes is not; the reply names that span by its id (#1.3) and the boundary — the collaborator, the parameter or return, the value that arrived and the value that left — before any code is changed: by reading, not by stepping through a debugger or adding prints
+
+## 5. Bisect by span, not by file
+
+**when:** only when the value went into the diverging span right and came out wrong, and what happens in between is more than that span's own few lines; otherwise the diverging span is the defect — go on to the fix
+
+```bash
+uv run pytest <the test that reproduces the symptom>
+```
+
+**done when:** only the sub-tree under the diverging id was read on each re-run — the spans whose id begins with it (#1.3, #1.3.1, #1.3.2) — and where the work inside that span is not traced, the collaborator it calls was wrapped with trace_object in the reproducing test, as the listing above wraps its inventory, and the run repeated, until the divergence sits in the smallest span that has it; never not_traced_field, __nt_not_traced__ or @not_traced to narrow — in Python they redact a value, they do not scope a trace
+
+## 6. Hand a defect in NarrativeTrace itself to narrativetrace-feedback
+
+**when:** only when the trace and the code disagree — a call the code makes has no span, a span shows a value the code did not pass, one span has two ids in two flavours — or the diverging span is inside NarrativeTrace; otherwise go on to the fix
+
+**done when:** narrativetrace-feedback was started with the span id and the value-free .nt — never a value from the trace — and the project's code was not changed to work around it; the loop ends with that hand-off
+
+## 7. Fix it in the diverging span, re-run the same input, read the same span
+
+```bash
+uv run pytest <the test that reproduces the symptom>
+```
+
+**done when:** the change is in the code of that span — the method the diverging id names, or what it calls — and the reproducing test passes; the same span, by the same id, now carries the value the symptom implied; a change anywhere else that makes the test pass silences the symptom and leaves the defect, so it is undone
+
+**verify:** `uv run pytest <the test that reproduces the symptom>`
+
+## 8. Check that nothing else moved
+
+```bash
+uv run python -c 'import pathlib; print(*sorted(pathlib.Path("narrative-traces/structural").rglob("*.nt")), sep="\n")'
+```
+
+**done when:** the fixed run's .nt was read whole and compared, line by line, with the call lines of the reproduction's .md — a red run writes no .nt (the .nt on disk is the last green one), so the shape before the fix is the .md's calls and ids without their values: the same calls in the same order under the same ids; a value fix moves no line of a value-free trace, and every line that did move is named by its id in the reply and either explained by the fix or undone
+
+## 9. Keep the reproduction as the regression test
+
+**done when:** the reproducing test stays in the suite with the input from the symptom and asserts the value the fixed span now carries — not only that nothing raises — so it fails when the fix is undone; its structural trace is what the pin below makes the baseline
+
+## 10. Turn approval mode on
+
+**when:** if approval mode is off — nothing sets NARRATIVETRACE_APPROVAL or `approval = true`, or the doctor's config.approval-mode finding fails; when it is already on, go straight to the run
+
+**done when:** `pyproject.toml` carries `approval = true` under `[tool.narrativetrace]`, and `.gitignore` carries the line `*.received.nt` so a review copy is never committed
+
+**verify:** `uv run python -c 'import sys; from narrativetrace.config import ConfigResolver; value = (ConfigResolver().resolve("approval", "") or "").strip().lower(); sys.exit(0 if value in {"1", "true", "yes", "on"} else 1)'`
+
+**failure:** the verify still exits 1 after the edit — the key sits under another table, the project also has a narrativetrace.toml (two configuration sources stop every run with DuplicateConfigurationError), or NARRATIVETRACE_APPROVAL=false is set in the environment, which wins over both. Fix: keep one source — `approval = true` directly under `[tool.narrativetrace]`, or at the top of narrativetrace.toml — unset the variable, and run the verify again
+
+## 11. Run the suite in approval mode and show every .received.nt
+
+```bash
+uv run pytest || true
+uv run python -c 'import pathlib; print(*sorted(pathlib.Path("test-narratives").rglob("*.received.nt")), sep="\n")'
+```
+
+**done when:** approval mode compares every traced test, not only the one this skill ran, so the run that writes the review copies is the whole suite; the first run of a test with no baseline fails on purpose — that failure is what writes its review copy — and the whole text of each .received.nt that run wrote is in the reply, not a summary of it — it holds names and shape and no value, which is why it is safe to commit once approved; where a .approved.nt already existed, the reply also names what the delta changed, by span id, in the program's own words, and whether it was meant
+
+## 12. Ask once whether to pin it, then stop the turn
+
+**done when:** the answer is the user's next message, never something assumed in this one. Do not run narrativetrace-approve before the user says yes — promoting is the pinning. Everything else — the report, every caveat, and what promoting does — goes before the question; the question is ONE sentence ending in a question mark and it is the reply's last line, so a reply whose last line is a sentence after the question has not asked it.
+
+## 13. Promote what was shown, and nothing else
+
+```bash
+uv run narrativetrace-approve
+```
+
+**done when:** each .approved.nt now holds exactly the text that was shown and no .received.nt is left beside it — `git status --short test-narratives` lists the new or changed .approved.nt files and nothing else; those are what get committed — and the whole suite passes again after the promotion
+
+**verify:** `uv run pytest`
+
+## 14. Report the root cause as the trace showed it
+
+**done when:** the root cause in the user's own terms — the span id where it diverged, the value that arrived and the value that left, the branch it took — and what the fix changed in that span; every claim cites the span id it rests on, from the .nt or .md read in this session: a claim without an id is not a claim. The report is written in full before the pin question, where the gate puts it, and the closing reply after the promotion names the span id again in its one-line summary of the cause
+
+## Which flavour answers which question
+
+| flavour | where | carries | answers |
+|---|---|---|---|
+| structural `.nt` | `narrative-traces/structural/<test module>/<test>.nt` | shape only: calls, order, nesting, parameter names, multiplicity, span ids — dozens of lines for a whole flow | did the flow do what I meant? |
+| Markdown narrative | `narrative-traces/traces/<test module>/<test>.md` | values (redacted), outcomes, durations | what value crossed this boundary? — read one span, by id |
+| indented text | `IndentedTextRenderer`, the failing test's output | the same values as plain text | the same question, in a console or a failure message |
+| sequence diagram | `narrative-traces/diagrams/<test module>/<test>.mmd` | who called whom, in order, across threads and tasks | ordering across components, threads and tasks |
+| approval delta | the failing test's message: `.received.nt` against `.approved.nt` under `test-narratives/` | what changed in the shape, citing both sides' ids | is this change intended? |
+| prose | `ProseRenderer` | narration for a person | explaining the flow to the user — never read it to check the code |
+
+Use the cheapest flavour that answers the question, and look at values only where the shape says
+to look. A span id (`#1`, `#1.3`, `#1.3.2`) is the span's position in the tree and the same in
+every flavour: find in the `.md` the span the `.nt` flagged, by its id. Redaction stays on — the
+deny-list and `[REDACTED]` are never turned off to see more; a redacted value that matters is
+reasoned about by its parameter name and the shape around it.
+
+## Shapes that mean something went wrong
+
+- a call made twice that the intent makes once
+- a call before its precondition — a notification before the payment that it announces
+- a branch never taken that the intent takes
+- a retry that masks a failure
+- a side effect inside a loop
+- a swallowed exception: a thrown outcome `!!` under a call that returned normally
+- a cleanup that never ran
+- a value crossing a boundary that should have been redacted
+
+## Always
+
+- Cite a span id for every claim about the trace. (an id points at one span in every flavour, so a reviewer can check the claim; a claim without one cannot be checked)
+- Narrow to one span before reading its values. (debugging is where values pay for themselves, but only on the span that diverged — a whole trace of values buries the one that matters)
+- Show the whole .received.nt before asking anything. (the baseline becomes the contract every later change is held to, and a person can only approve what they have actually read)
+- End the turn on the question, with nothing after it. (the answer is the user's next message, never something assumed in this one. Do not run narrativetrace-approve before the user says yes — promoting is the pinning.)
+
+## Never
+
+- Never change code before the diverging span is named. (a fix made before the trace says where the value went wrong is a guess, and a guess that turns the test green hides the defect it missed)
+- Never make the symptom go away somewhere other than the diverging span. (a correction downstream, a caught exception or a changed expectation silences the symptom and leaves the defect for the next caller of that span)
+- Never turn redaction off to see more. (a redacted value that matters is reasoned about by its name and shape; turning redaction off puts the user's secrets in the transcript)
+- Never promote a baseline in the turn that asked. (approval is the user's next message -- a yes assumed in the same turn is not one)
+- Never edit the .received.nt after showing it. (what was approved has to be what is promoted, so a changed run is rendered again and shown again)
+- Never commit a .received.nt. (it is the review copy; the committed contract is the .approved.nt)

{narrativetrace-0.2.0 → narrativetrace-0.3.0}/src/narrativetrace/_skills/agents/narrativetrace-doctor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: narrativetrace-doctor
-description: "Diagnoses a NarrativeTrace Python install and configuration. Use when nothing is being traced, no trace output files appear, DuplicateConfigurationError shows up on startup, a *args method's parameters render as one args: [...] value, or you are not sure NarrativeTrace is wired up correctly. Checks the interpreter and pytest versions, that all eight narrativetrace-* packages agree on one version, NARRATIVETRACE_OUTPUT, that the pytest plugin is registered and not disabled, whether the NarrativeTrace agent skills are installed and current, unrecognized narrativetrace.toml keys, an imported-but-unused not_traced_field/__nt_not_traced__ marker, whether redaction is proven in a test, and stale approval-trace diffs. Read-only -- makes no changes. Say 'check my narrativetrace setup', 'is narrativetrace broken', or 'why isn't anything being traced' to invoke it."
+description: "Diagnoses a NarrativeTrace Python install and configuration. Use when nothing is being traced, no trace output files appear, DuplicateConfigurationError shows up on startup, a *args method's parameters render as one args: [...] value, or you are not sure NarrativeTrace is wired up correctly. Checks the interpreter and pytest versions, that all eight narrativetrace-* packages agree on one version, NARRATIVETRACE_OUTPUT, that the pytest plugin is registered and not disabled, whether the NarrativeTrace agent skills are installed and current, unrecognized narrativetrace.toml keys, an imported-but-unused not_traced_field/__nt_not_traced__ marker, whether redaction is proven in a test, stale approval-trace diffs, and approved baselines nothing compares because approval mode is off. Read-only -- makes no changes. Say 'check my narrativetrace setup', 'is narrativetrace broken', or 'why isn't anything being traced' to invoke it."
 ---
 
 # narrativetrace-doctor
@@ -14,7 +14,7 @@ uv run narrativetrace doctor || true
 **verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
 report = json.load(sys.stdin)
 findings = report.get("findings")
-sys.exit(1 if not isinstance(findings, list) or len(findings) != 12 else 0)
+sys.exit(1 if not isinstance(findings, list) or len(findings) != 19 else 0)
 '`
 
 **failure:** the CLI's JSON output does not parse, or is missing findings — the CLI crashed instead of reporting a finding. Fix: re-run `uv run narrativetrace doctor --json` directly and read the raw output -- a crash here is a doctor bug, never a project finding
@@ -81,6 +81,7 @@ else:
 ## Always
 
 - Run the doctor CLI and read its report before making any change. (the tested tooling already computed the finding -- re-deriving it by hand risks disagreeing with what ships)
+- If a check is wrong, or its fix does not work, report it with the narrativetrace-feedback skill. (a wrong finding costs every project that hits it until somebody says so, and that skill shows you the whole report and files nothing without your answer)
 
 ## Never
 

narrativetrace-0.3.0/src/narrativetrace/_skills/agents/narrativetrace-feedback/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: narrativetrace-feedback
+description: "Reports a defect in NarrativeTrace itself -- the library, the doctor, an agent skill, or the published install prompt. Use when a doctor finding is wrong or its fix does not work, when a skill step cannot be followed or its verify cannot be met, when the install prompt is wrong, or when the library misbehaves and the project is configured correctly. Drafts the report from this project (the install coordinates, the doctor's own JSON report, and at most one structural trace), refuses to write one that carries a value from your traces and names the rule that refused it, shows you the whole draft, and then asks once whether to file it publicly. Files nothing without your answer and sends nothing anywhere. Say 'report this to NarrativeTrace', 'the doctor's fix did not work', or 'file a bug about this skill' to invoke it."
+---
+
+# narrativetrace-feedback
+
+## 1. Gather what the report needs
+
+```bash
+uv run narrativetrace doctor || true
+```
+
+**verify:** `uv run narrativetrace doctor --json | uv run python -c 'import json, sys
+report = json.load(sys.stdin)
+findings = report.get("findings")
+sys.exit(1 if not isinstance(findings, list) or len(findings) != 19 else 0)
+'`
+
+**failure:** the CLI is not found, or the project has no pyproject.toml — NarrativeTrace is not installed in this project's environment. Fix: report under the prompt or library category instead -- those do not need a doctor report
+
+## 2. Draft the report and let the gate check it
+
+```bash
+uv run narrativetrace feedback draft --category <category> --step "<where it happened>" --did "<what you did>" --happened "<what happened>" --expected "<what you expected>"
+```
+
+**verify:** `uv run python -c 'import pathlib, sys
+root = pathlib.Path("build/narrativetrace/feedback")
+paths = [root / (stem + ".md") for stem in ("feedback-draft", "feedback-body")]
+sys.exit(0 if all(p.is_file() and p.stat().st_size for p in paths) else 1)
+'`
+
+**failure:** the command exits 2 naming a vf.* rule — a field carries a value from this project's own run -- a rendered call line, an elapsed time, a credential-shaped string, an address. Fix: rewrite that one field to describe what happened instead of pasting it, and draft again; never work around the rule by moving the text to another field
+
+## 3. Show the whole draft, not a summary of it
+
+```bash
+uv run python -c 'import pathlib
+draft = pathlib.Path("build/narrativetrace/feedback") / ("feedback-draft" + ".md")
+print(draft.read_text(encoding="utf-8"))
+'
+```
+
+## 4. Ask once whether to file it, then stop the turn
+
+## 5. Print the way to file it, and nothing else
+
+```bash
+uv run narrativetrace feedback url --category <category> --step "<where it happened>" --did "<what you did>" --happened "<what happened>" --expected "<what you expected>"
+```
+
+**verify:** `uv run narrativetrace feedback url --category <category> --step "<where it happened>" --did "<what you did>" --happened "<what happened>" --expected "<what you expected>" | uv run python -c 'import sys
+sys.exit(0 if "/issues/new?template=" in sys.stdin.read() else 1)
+'`
+
+## Always
+
+- Show the whole draft before asking anything. (filing is public and permanent, and a person can only approve what they have actually read)
+- End the turn on the question, with nothing after it. (the answer is the user's next message, never something assumed in this one. Do not print the issue URL or run gh before the user says yes — showing the URL is the filing.)
+- Ask in the user's own language. (the report may be written in any language, and a question nobody understands is not a question)
+- Tell the user that filing is public, under their own account, before they answer. (a public issue shows that their project uses NarrativeTrace, and that is their decision to make knowingly)
+- With the printed URL, name the file to paste and where. (the URL carries the short fields only; the body is never in it, so the user must paste the body file the verb names into the form's last box)
+
+## Never
+
+- Never attach a rendered trace, a log file or a source file. (those carry the values from the user's own run; the structural trace carries the same shape of the same call without any of them, and the verb attaches it on its own)
+- Never file in the turn that asked. (approval is the user's next message -- a yes assumed in the same turn is not one)
+- Never edit the draft after showing it. (what was approved has to be what is filed, so a changed report is drafted again and shown again)
+- Never open the URL or run the printed command. (submitting is the user's act, in their own browser or their own shell, under their own account)
+- Never route a rule's refusal around the gate. (a field that cannot be filed is a field to rewrite, not to move somewhere the rule does not look)