aftersight 0.1.0__tar.gz

aftersight-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e '.[docs]'
+      - run: mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

aftersight-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,26 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # Trusted publishing: PyPI verifies this workflow through OIDC, so there is
+    # no API token to store or rotate. Register the publisher on PyPI with
+    # owner nebulaanish, repository aftersight, workflow release.yml and
+    # environment pypi, all four of which must match what is below.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e . build
+      - run: python tests/test_formats.py
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

aftersight-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+.runs/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+.pytest_cache/
+.ruff_cache/
+site/

aftersight-0.1.0/AGENTS.md

@@ -0,0 +1,101 @@
+# AGENTS.md
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
+
+
+
+# Guidelines: What Defines a Valid Test Case
+
+Strictly enforce this standard when writing or evaluating tests. Reject any test case exhibiting invalid anti-patterns.
+
+---
+
+## 1. Valid Test Case Criteria
+A valid test must satisfy ALL of the following:
+
+- **Single Concept:** Tests exactly ONE behavior per test function.
+- **Black-Box Testing:** Verifies public interfaces and inputs/outputs—never internal private implementation details.
+- **100% Deterministic:** Zero reliance on ambient clock (`Date.now()`), random seeds, external APIs, or dirty DB state.
+- **Explicit AAA:** Structured strictly as Arrange (setup), Act (trigger), Assert (check).
+- **Refactor-Resistant:** Must pass if internal code is completely refactored without breaking the public contract.
+- **High Information Density:** Focuses on realistic boundaries (`0`, `null`, empty arrays, max limits) or explicit error modes.
+
+---
+
+## 2. Invalid Test Case Anti-Patterns (Immediate Rejection)
+
+- ❌ **Implementation Coupling:** Asserting internal helper execution order or checking private class state.
+- ❌ **Tautologies:** Re-implementing production logic inside the test setup or asserting simple pass-through getters.
+- ❌ **Multi-Scenario Bloat:** Single tests containing sequential user actions, >3 independent assertions, or multiple business rules.
+- ❌ **Over-Mocking:** Mocking simple domain models or internal helper classes instead of using real instances or factories.
+- ❌ **Flakiness:** Relying on arbitrary `sleep()` calls, live network calls, or unordered array checks.
+
+---
+
+## Output Verification Checklist
+Before outputting code, verify:
+1. Is the test name `<Method>_<Scenario>_<ExpectedResult>`?
+2. Does it test what the code DOES, not HOW it does it?
+3. If the implementation changes internally, will this test still pass?

aftersight-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Balaram
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aftersight-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: aftersight
+Version: 0.1.0
+Summary: Observability infrastructure for self-improving agents
+Project-URL: Homepage, https://github.com/nebulaanish/aftersight
+Project-URL: Documentation, https://nebulaanish.github.io/aftersight/
+Project-URL: Source, https://github.com/nebulaanish/aftersight
+Project-URL: Issues, https://github.com/nebulaanish/aftersight/issues
+Author-email: Balaram <balaramneu@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,llm,observability,opentelemetry,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: opentelemetry-api>=1.20
+Requires-Dist: opentelemetry-sdk>=1.20
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs<2; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# aftersight
+
+Observability infrastructure for self-improving agents.
+
+An agent cannot improve on a run it cannot read. Aftersight writes every
+run into the repository as plain files, so the agent can read its own
+history with the tools it already has.
+
+## The problem
+
+Coding agents already explore repositories with file search, shell commands and
+plain text. Agent telemetry usually lives somewhere else: behind a dashboard,
+an API or a remote MCP server.
+
+Aftersight writes the evidence into the repository instead. A coding agent can
+use the tools it already knows to:
+
+1. diagnose why one run failed;
+2. find failures that recur across runs;
+3. inspect the exact inputs and outputs of models and tools.
+
+## Start in one command
+
+```bash
+pip install aftersight
+aftersight run python my_agent.py
+```
+
+No account, API key, service or initialization step is required.
+
+## Ask your coding agent
+
+Each telemetry root includes a `NAVIGATE.md` with verified `rg` and `jq`
+recipes. Tell your coding agent:
+
+> Read `.runs/NAVIGATE.md` and find out why the latest run failed.
+
+For Claude Code, the optional command below installs the bundled navigation
+skill:
+
+```bash
+aftersight skill
+```
+
+## What gets recorded
+
+```text
+.runs/
+  NAVIGATE.md
+  index.jsonl
+  latest -> runs/<run_id>
+  runs/<run_id>/
+    outline.md
+    agent.logs
+    trace.jsonl
+    analytics.json
+    meta.json
+    blobs/
+    artifacts/
+```
+
+`outline.md` is the short map. `agent.logs` is the complete readable
+transcript. `trace.jsonl`, `analytics.json` and `index.jsonl` are stable
+machine-readable views for scripts and frontends. The same `#seq` anchor
+identifies an event in every projection.
+
+## Use it from Python
+
+```python
+import aftersight
+
+aftersight.start()
+```
+
+Add explicit detail only where it helps:
+
+```python
+with aftersight.span("planner"):
+    with aftersight.span("web_search", kind="tool", args={"q": query}) as span:
+        span.output = search(query)
+
+@aftersight.trace
+def read_file(path): ...
+
+aftersight.log("cache miss", key=key)
+```
+
+## Works with OpenTelemetry
+
+Aftersight attaches a span processor to the application's existing
+OpenTelemetry setup and reads common `gen_ai.*`, OpenInference and generic
+input/output attributes. Frameworks that already emit compatible spans need no
+aftersight-specific adapter. An existing tracer provider and its exporters are
+left in place.
+
+## How it compares
+
+[LangSmith](https://docs.langchain.com/langsmith/observability-concepts),
+[Langfuse](https://langfuse.com/docs/api-and-data-platform/features/observations-api),
+[Phoenix](https://arize.com/docs/phoenix/tracing/how-to-tracing/importing-and-exporting-traces/extract-data-from-spans)
+and [Braintrust](https://www.braintrust.dev/docs/integrations/developer-tools/mcp)
+provide mature observability with dashboards and programmatic access through
+APIs, exports or MCP.
+
+Aftersight has a narrower default: ordinary files in the repository, with no
+hosted project, credentials or remote query round trips. Those platforms are a
+better fit when you need centralized durability, team dashboards or managed
+evaluation workflows. See [Why aftersight exists](docs/why.md) for the fuller
+comparison.
+
+## Local by default
+
+Aftersight itself makes no network requests and does not upload telemetry.
+Payload redaction is enabled by default, and the run folder is added to
+`.gitignore` when it is first created.
+
+If the application already has an OpenTelemetry exporter, that exporter may
+still send its own spans. Aftersight can run in production, but local disk can
+disappear with an ephemeral, replaced or failed host, so it should not be the
+only durable production record.
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md)
+- [Framework support](docs/frameworks.md)
+- [Navigating runs](docs/navigating.md)
+- [Python API](docs/reference/api.md)
+- [Run folder format](docs/reference/run-folder.md)
+- [Architecture](docs/design/architecture.md)
+
+Full documentation: **https://nebulaanish.github.io/aftersight/**

aftersight-0.1.0/README.md

@@ -0,0 +1,131 @@
+# aftersight
+
+Observability infrastructure for self-improving agents.
+
+An agent cannot improve on a run it cannot read. Aftersight writes every
+run into the repository as plain files, so the agent can read its own
+history with the tools it already has.
+
+## The problem
+
+Coding agents already explore repositories with file search, shell commands and
+plain text. Agent telemetry usually lives somewhere else: behind a dashboard,
+an API or a remote MCP server.
+
+Aftersight writes the evidence into the repository instead. A coding agent can
+use the tools it already knows to:
+
+1. diagnose why one run failed;
+2. find failures that recur across runs;
+3. inspect the exact inputs and outputs of models and tools.
+
+## Start in one command
+
+```bash
+pip install aftersight
+aftersight run python my_agent.py
+```
+
+No account, API key, service or initialization step is required.
+
+## Ask your coding agent
+
+Each telemetry root includes a `NAVIGATE.md` with verified `rg` and `jq`
+recipes. Tell your coding agent:
+
+> Read `.runs/NAVIGATE.md` and find out why the latest run failed.
+
+For Claude Code, the optional command below installs the bundled navigation
+skill:
+
+```bash
+aftersight skill
+```
+
+## What gets recorded
+
+```text
+.runs/
+  NAVIGATE.md
+  index.jsonl
+  latest -> runs/<run_id>
+  runs/<run_id>/
+    outline.md
+    agent.logs
+    trace.jsonl
+    analytics.json
+    meta.json
+    blobs/
+    artifacts/
+```
+
+`outline.md` is the short map. `agent.logs` is the complete readable
+transcript. `trace.jsonl`, `analytics.json` and `index.jsonl` are stable
+machine-readable views for scripts and frontends. The same `#seq` anchor
+identifies an event in every projection.
+
+## Use it from Python
+
+```python
+import aftersight
+
+aftersight.start()
+```
+
+Add explicit detail only where it helps:
+
+```python
+with aftersight.span("planner"):
+    with aftersight.span("web_search", kind="tool", args={"q": query}) as span:
+        span.output = search(query)
+
+@aftersight.trace
+def read_file(path): ...
+
+aftersight.log("cache miss", key=key)
+```
+
+## Works with OpenTelemetry
+
+Aftersight attaches a span processor to the application's existing
+OpenTelemetry setup and reads common `gen_ai.*`, OpenInference and generic
+input/output attributes. Frameworks that already emit compatible spans need no
+aftersight-specific adapter. An existing tracer provider and its exporters are
+left in place.
+
+## How it compares
+
+[LangSmith](https://docs.langchain.com/langsmith/observability-concepts),
+[Langfuse](https://langfuse.com/docs/api-and-data-platform/features/observations-api),
+[Phoenix](https://arize.com/docs/phoenix/tracing/how-to-tracing/importing-and-exporting-traces/extract-data-from-spans)
+and [Braintrust](https://www.braintrust.dev/docs/integrations/developer-tools/mcp)
+provide mature observability with dashboards and programmatic access through
+APIs, exports or MCP.
+
+Aftersight has a narrower default: ordinary files in the repository, with no
+hosted project, credentials or remote query round trips. Those platforms are a
+better fit when you need centralized durability, team dashboards or managed
+evaluation workflows. See [Why aftersight exists](docs/why.md) for the fuller
+comparison.
+
+## Local by default
+
+Aftersight itself makes no network requests and does not upload telemetry.
+Payload redaction is enabled by default, and the run folder is added to
+`.gitignore` when it is first created.
+
+If the application already has an OpenTelemetry exporter, that exporter may
+still send its own spans. Aftersight can run in production, but local disk can
+disappear with an ephemeral, replaced or failed host, so it should not be the
+only durable production record.
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md)
+- [Framework support](docs/frameworks.md)
+- [Navigating runs](docs/navigating.md)
+- [Python API](docs/reference/api.md)
+- [Run folder format](docs/reference/run-folder.md)
+- [Architecture](docs/design/architecture.md)
+
+Full documentation: **https://nebulaanish.github.io/aftersight/**

aftersight-0.1.0/aftersight/__init__.py

@@ -0,0 +1,21 @@
+"""Observability infrastructure for self-improving agents.
+
+    import aftersight
+    aftersight.start()
+
+Or, with no code change at all:
+
+    aftersight run python my_agent.py
+"""
+
+from aftersight.run.api import (
+    artifact_dir,
+    current,
+    log,
+    span,
+    start,
+    trace,
+)
+
+__all__ = ["start", "span", "trace", "log", "current", "artifact_dir"]
+__version__ = "0.1.0"

aftersight-0.1.0/aftersight/assets/NAVIGATE.md

@@ -0,0 +1,129 @@
+# Navigating these runs
+
+You are a coding agent. This directory is the execution history of the agent
+system in this repo. Read this file once, then use `rg` and `jq`.
+
+## Layout
+
+```
+index.jsonl                one line per run, start here for "which run?"
+latest -> runs/<run_id>    most recent run
+sessions/<session_id>      -> the run folder that session resumed into
+runs/<run_id>/
+  outline.md               folded map of the run, read this first
+  agent.logs               full transcript, nothing truncated
+  trace.jsonl              same events, machine-readable, has parent_seq
+  analytics.json           status, timings, per-agent cost, error list
+  meta.json                framework, git sha, argv, attempts[]
+  blobs/<sha>.txt          payloads over 8 KB, plain text
+  artifacts/               whatever the app chose to keep
+```
+
+Run ids are `YYYYMMDD_HHMMSS_hash`, so they sort chronologically. Glob run
+files as `runs/*/...` and never from the root: `latest` and `sessions/` are
+symlinks into `runs/`, so a root glob counts every run twice.
+
+## The three-step loop
+
+1. **Which run?** `index.jsonl`
+2. **What happened in it?** `runs/<run_id>/outline.md`, then jump to a `#seq`
+3. **Exactly what went in and out?** `runs/<run_id>/agent.logs` at that `#seq`
+
+## Anchors
+
+Every event has a zero-padded sequence number. It is the same number in
+`outline.md`, `agent.logs` and `trace.jsonl`, so you can move between them:
+
+```sh
+rg -n '^#0016 ' latest/agent.logs          # jump to one event
+rg -n '#0016' runs/<run_id>/               # every mention of it
+```
+
+Multi-line payloads are framed. The closing line repeats the anchor, so a hit
+landing inside a block can find both edges:
+
+```
+#0004 14:22:35.512  +2.4s  llm.response  triage   stop=end_turn · 386 tok · $0.0005
+┌──────────────────────────────────
+{"decision": "work", ...}
+└─ #0004 end · 86 B ───────────────
+```
+
+Column 3 is the delta from the previous event. Scan it to find slow steps. A
+negative delta means an event whose span declared its kind late and was therefore
+placed at its end rather than its start; the timestamp is still correct.
+
+## Recipes
+
+```sh
+# failed runs, newest last
+jq -r 'select(.status!="ok") | "\(.run_id) \(.errors) errs $\(.cost_usd) \(.last_error)"' index.jsonl
+
+# the most common failure across all history
+rg -oN '"error_type": "[A-Za-z]+"' runs/*/trace.jsonl | cut -d'"' -f4 | sort | uniq -c | sort -rn
+
+# every error in one run, with its anchor
+#   filter on payload.error_type, not .status, agent.end also carries status "error"
+jq -r 'select(.payload.error_type) | "#\(.seq|tostring|("0000"+.)[-4:]) \(.name) \(.payload.error_type): \(.payload.error)"' latest/trace.jsonl
+
+# what a tool was actually called with, every time
+rg -N '^#\d+ .* tool\.call     run_python' runs/*/agent.logs
+
+# read one event and its payload block
+rg -n -A40 '^#0023 ' latest/agent.logs
+
+# where the money went
+jq -r '.cost.by_agent | to_entries[] | "\(.key) $\(.value.cost_usd)"' latest/analytics.json
+
+# slowest steps in a run, exclude run.* or the run total wins every time
+jq -r 'select(.dur_ms!=null and (.type|startswith("run.")|not)) | "\(.dur_ms)ms #\(.seq|tostring|("0000"+.)[-4:]) \(.type) \(.name)"' latest/trace.jsonl | sort -rn | head
+
+# did this session get resumed, and why did the earlier attempt end?
+jq '.attempts' latest/meta.json
+rg -n '^==== attempt|^---- attempt' latest/agent.logs
+
+# a prompt too big to inline
+rg -n 'blobs/' latest/agent.logs        # find the pointer
+rg -n 'PCA' latest/blobs/*.txt          # then grep the blob like any text file
+
+# same failure across runs, or just this one?
+rg -lN 'TimeoutError' runs/*/agent.logs
+```
+
+## Counting things correctly
+
+Three traps, each of which silently produces a wrong answer rather than an error:
+
+- `status: "error"` appears on `agent.end` too. Count failures by
+  `payload.error_type`.
+- `run.end` carries the run total in `dur_ms`. Exclude `run.*` when ranking steps.
+- `agent.end` carries a cost rollup. Sum leaf costs, or read
+  `analytics.json → cost.by_agent`.
+
+## Event types
+
+`run.start` `run.resume` `run.end` · `agent.start` `agent.end` ·
+`llm.prompt` `llm.response` · `tool.call` `tool.result` `tool.error` ·
+`error` · `artifact` · `log`
+
+Namespaced on purpose: `rg 'tool\.'` gets all tool activity, `rg '\.error'`
+gets every failure shape.
+
+## Resume
+
+A session that is resumed appends into the same run folder under a new
+`==== attempt N ====` banner. Sequence numbers continue across attempts and
+are never reused. An attempt that died without `run.end` is marked
+`---- attempt N ended ... without run.end ----`, which is how you tell a crash
+from a clean failure.
+
+## When you are looking for a systemic problem
+
+Do not read one run. Aggregate first:
+
+```sh
+rg -oN '"error_type": "[A-Za-z]+"' runs/*/trace.jsonl | cut -d'"' -f4 | sort | uniq -c | sort -rn
+jq -s 'group_by(.status)[] | {status: .[0].status, n: length}' index.jsonl
+```
+
+Then open the cheapest run that shows the pattern, not the biggest.

aftersight-0.1.0/aftersight/assets/skill/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: aftersight
+description: Use when investigating how this project's agent behaved: a failed or slow agent run, a recurring tool failure, unexpected model output, rising cost, or any question about what an agent actually sent and received. Reads the execution traces in .runs/.
+---
+
+# Reading this project's agent traces
+
+Agent runs in this repo record to `.runs/`. That directory is the evidence for
+what an agent actually did. Read it before theorising about behaviour.
+
+Start with `.runs/NAVIGATE.md`. It documents the layout, the `#seq` anchor
+scheme and a set of verified `rg`/`jq` recipes.
+
+## The loop
+
+1. `.runs/index.jsonl` holds one line per run. Pick the run.
+2. `.runs/runs/<run_id>/outline.md` is the folded map. Find the `#seq` that
+   matters.
+3. `.runs/runs/<run_id>/agent.logs` at that anchor has the exact prompt,
+   completion, tool arguments or traceback.
+
+## Rules that keep answers correct
+
+- Aggregate before you read. One run shows an incident; `runs/*/trace.jsonl`
+  shows whether it is systemic.
+- Glob as `runs/*/…`. `latest` and `sessions/` are symlinks into `runs/`, so
+  globbing the root double-counts.
+- Count failures by `payload.error_type`, not `status == "error"`, because
+  `agent.end` carries that status too.
+- Exclude `run.*` when ranking slow steps; `run.end` holds the run total.
+- A prompt over 8 KB lives in `blobs/` as plain text. Grep it like any file.
+- Sequence numbers continue across a resumed session, and an attempt that died
+  without `run.end` is marked as such. A crash and a clean failure are different
+  findings.
+
+## When asked to improve the agent
+
+Ground every claim in an anchor. "Tool `x` timed out in 4 of the last 9 runs
+(`#0044`, `#0071`, …)" is actionable; "the executor seems flaky" is not.