narrativetrace 0.2.0__tar.gz → 0.4.0__tar.gz

{narrativetrace-0.2.0 → narrativetrace-0.4.0}/.gitignore

@@ -28,3 +28,8 @@ build/
 # narrativetrace-pytest's default per-test artifact directory -- on by default, opt out with
 # NARRATIVETRACE_OUTPUT=false (see documentation/what-to-commit.md)
 narrative-traces/
+
+# The recipe scenario's approved baselines are source; the files an approval run writes beside them
+# are not (documentation/what-to-commit.md)
+examples/recipes/checkout/test-narratives/**/*.received.nt
+examples/recipes/checkout/test-narratives/**/*.incomplete.nt

{narrativetrace-0.2.0 → narrativetrace-0.4.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.4.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-16 for this version)
 
 Change License:       Apache License, Version 2.0
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: narrativetrace
-Version: 0.2.0
+Version: 0.4.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.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "narrativetrace"
-version = "0.2.0"
+version = "0.4.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.4.0}/src/narrativetrace/__init__.py

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

{narrativetrace-0.2.0 → narrativetrace-0.4.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.4.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.4.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.4.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.4.0/src/narrativetrace/_skills/agents/narrativetrace-explain/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: narrativetrace-explain
+description: "Use when someone asks what an application or a flow actually does, with nothing broken and no change needing verification: 'show me what my application actually does', 'walk me through what happens when a user checks out', 'I inherited this service, how does an order flow', 'what does this endpoint call'. Load it BEFORE reading source files to describe them: it explains a Python application by running one scenario with NarrativeTrace on and reading the trace of what happened \u2014 evidence of the run, not a reading of the code. Decides first whether a trace is worth it: a question ten lines of source answer is answered from the source, with no install and no run. Otherwise it runs one existing test or entry point for that flow \u2014 installing through add-narrative-tracing when the project has none \u2014 reads the value-free structural trace, and explains the run by span id, marking what it inferred and naming the code no span covered. Hands a defect to narrativetrace-debug, a change to narrativetrace-verify."
+---
+
+# narrativetrace-explain
+
+## 1. Decide whether the source already answers it, and say so
+
+**done when:** before anything is installed or run, the reply says which it is: 'reading the source: <the reason>' when the question is about a pure function, one class with no collaborator, or a path ten lines of source settle — the answer is then that reading, with no install and no run, and the skill ends there; or 'tracing: <the reason>' when the flow crosses two or more collaborators over a boundary, branches, retries, runs async or concurrently, carries state between calls, or is code nobody in this session wrote. A whole flow's .nt is dozens of lines: cheap where the path is not obvious, waste where the source is already the answer
+
+## 2. Choose the one scenario that already exercises the flow
+
+**done when:** the reply names ONE scenario — an existing test, or the entry point a reader would run — and which call of the flow asked about it drives; a scenario is written only where the project has none, and the reply says which of the two it is. Two scenarios is two traces to read where one answers the question
+
+## 3. Install tracing first when the project has none
+
+**when:** only when the project has no NarrativeTrace at all — no dependency on it in pyproject.toml and nothing under narrative-traces; where it is already installed, go straight to the run
+
+**done when:** add-narrative-tracing was followed to its own first trace and this skill resumed at the run below; nothing beyond that install was changed — an explanation does not refactor the code it is about
+
+## 4. Run that one scenario with tracing on
+
+**when:** the project already has a test or entry point that exercises the flow — run that one, as it is; where none exists, add-narrative-tracing's own first-trace step is how one gets written, and it comes back here
+
+```bash
+uv run pytest <the test that exercises the flow you were asked about>
+```
+
+**done when:** the scenario ran and wrote a trace of its own: narrative-traces/structural holds an .nt for it, and narrative-traces/traces the .md beside it — a run that writes nothing is the failure below, never an answer; and the scenario ran as it was found, because a scenario edited to make the flow clearer is no longer the flow
+
+**failure:** the scenario runs but nothing appears under narrative-traces — the test does not request the narrative_trace fixture, the collaborators on the flow are not wrapped with it, or the pytest plugin is not registered, so there is nothing to read. Fix: run narrativetrace-doctor and apply its fix, then run the scenario again
+
+## 5. Read the structural trace first, in the order it ran
+
+```bash
+uv run python -c 'import pathlib; print(*sorted(pathlib.Path("narrative-traces/structural").rglob("*.nt")), sep="\n")'
+```
+
+**done when:** the .nt the scenario just wrote was opened and read whole before any value was looked at, and the reply walks it in its own order by span id (#1, #1.1, #1.2): which call ran under which, how many times, and which branch the run took — the flavours below say which file answers which question
+
+## 6. Open values only where the question needs one
+
+**when:** only when the question is about a value that crossed a boundary, or about where the time went — the .nt carries neither; otherwise the shape is the whole answer
+
+```bash
+uv run python -c 'import pathlib; print(*sorted(pathlib.Path("narrative-traces/traces").rglob("*.md")), sep="\n")'
+```
+
+**done when:** only the spans the question needs were read in the .md narrative, found by the id the .nt gave them — not the whole file; a [REDACTED] value stays redacted and is reasoned about by its parameter name and the shape around it
+
+## 7. Hand off when it stops being an explanation
+
+**when:** only when the run shows something wrong — one of the shapes below, or a value that is not what the flow implies — or a change of this session's own is what the user is really asking about; otherwise go on to the explanation
+
+**done when:** narrativetrace-debug was started, with the span id of the first call that looks wrong, when the run showed a defect; or narrativetrace-verify when what needs reading is a change this session made. The explanation written so far goes with the hand-off, and this skill fixes nothing itself
+
+## 8. Explain the run by span id, and mark what you inferred
+
+**done when:** the explanation is in the user's own words and in the trace's own order: the calls the flow made, each claim citing the span id it rests on — a claim without an id is not a claim, and only ids in the .nt or .md read in this session count — the branch it took, and where the time went when that was the question. Every sentence that goes beyond what the trace shows is marked as an inference, and the last part names what was NOT observed: the code no span covers, because only wrapped or intercepted code has one
+
+## 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
+
+- Answer from the source when ten lines of source answer the question (an install and a run cost the user time and tokens, and a trace of a pure function shows one call; the trace earns its keep where the path is not obvious — two collaborators over a boundary, a branch, a retry, state carried between calls)
+- 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)
+- Separate what the trace showed from what you inferred. (a reader cannot check a claim that mixes the two, and the inference is exactly where an explanation is wrong while sounding most certain)
+
+## Never
+
+- Never present an unobserved call as something the trace showed. (only wrapped or intercepted code has a span, so a call no span covers is an inference; naming it as observed is how an explanation becomes confidently wrong about the part nobody measured)
+- Never change the code in order to explain it. (the user asked what the code does, not for a change — wrapping one more collaborator inside a scenario is reading, editing what runs in production is not)
+- 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)