docs

Docs

PREREQUISITE: Read subtext:shared for MCP conventions.

Tool catalog and judgment rules for agent-produced proof documents. Doc tools are available on the subtext MCP server.

The document tools are intentionally generic: the server does not know about bug-fix vs. ux-review vs. verification workflows. Pass your preferred structure via doc-create(content: ...); this skill ships opinionated templates below.

MCP Tools

Tool	Description
doc-create	Open a new proof document with a title and optional seed markdown
doc-update	Edit the document: replace text, append content, or update metadata
doc-attach	Attach evidence (screenshot, replay, log, diff, report) into a named section
doc-close	Finalize the document, write a permanent snapshot, get a stable URL
doc-read	Read the current or a past version of a document
doc-diff	Diff two document versions
doc-list	List open or closed documents, optionally filtered by tag, ref, trace_id, or status

Lifecycle

doc-create → [doc-update / doc-attach]* → doc-close

• doc-create writes the title, auto-managed metadata line, and (if content is provided) your seed markdown. Without content, it creates a document with a single empty ## Evidence section.
• doc-update and doc-attach fill evidence during work.
• doc-close writes an immutable version snapshot (v1.md, v2.md, …) and marks the doc complete, partial, or abandoned.
• Open docs auto-close as abandoned after 24h of inactivity.
• A closed doc can be reopened by calling doc-update on it. The metadata header will switch to Latest closed: vN | Draft in progress until the next doc-close bumps to v{N+1}.

Seed templates

Pass one of these as content on doc-create to shape the document up front. Agents may edit headings and add sections freely afterwards via doc-update.

bug-fix

## Context
<!-- What broke, how it was observed, what the expected behavior was -->

## Root Cause
<!-- Why it broke -->

## Before
<!-- Evidence of the bug: screenshots, session replays, console errors -->

## Changes
<!-- Files modified, approach taken -->

## After
<!-- Evidence the fix works: screenshots, test output -->

## Test Results
<!-- Repro check, regression checks -->

## Session Replays
<!-- Viewer URLs -->

ux-review

## Context
<!-- What was reviewed and why -->

## Flow Summary
<!-- The user journey observed -->

## Friction Points
<!-- Where users stalled, backtracked, or failed -->

## Positive Patterns
<!-- What worked well -->

## Evidence
<!-- Auto-populated by doc-attach -->

## Session Replays
<!-- Viewer URLs -->

verification

## Context
<!-- What is being verified, against what claim or spec -->

## Before
<!-- Observed state before verification -->

## Changes
<!-- Diffs, commits, or other artifacts representing what was modified -->

## After
<!-- Observed state after -->

## Test Matrix
<!-- The cases that were exercised -->

## Evidence
<!-- Auto-populated by doc-attach -->

changeset

## Context
<!-- The batch of changes and why -->

## Changes
<!-- Files modified, approach, notable decisions -->

## Before / After
<!-- Visual or behavioral comparison -->

## Test Results
<!-- Confidence evidence -->

## Evidence
<!-- Auto-populated by doc-attach -->

Attaching evidence

doc-attach has four source modes. Provide exactly one:

Mode	Use when	Params
base64_data + content_type	Binary content (images, PDF) generated in-session	label, section, render_as
text + content_type	Plain-text content (markdown plans, logs, JSON). Avoids base64 inflation.	label, section, render_as
artifact_id	Referencing a file from a previous artifact-upload	label, section, render_as, optionally artifact_ext
url	External URL (session replay, viewer link, Grafana, Loom)	label, section, render_as

Additional params:

• section — markdown heading to insert under. Defaults to Evidence. Creates the section at the bottom if absent.
• render_as — image inlines as ![label](url), link inserts - [label](url). Defaults to link. Use image for screenshots.

GCS-backed attachments (base64_data, text, artifact_id) are stored as gs:// URIs in the markdown and signed at render time, so closed documents stay readable indefinitely.

When to create a document

Create a doc at the start of any significant workflow:

• Running the proof skill for a code change (create at Step 1, close at Step 7)
• Starting a multi-step changeset (PR review, deployment verification)
• Any time the user will want a permanent record of what the agent did and why

Pass the returned doc_id to any subagents so they can attach evidence to the same document.

When to attach evidence

Attach at every capture point. Typical patterns:

• Screenshot of observed bug → doc-attach(render_as: "image", section: "Before", label: "Observed bug", base64_data: ...)
• Fix diff → doc-attach(render_as: "link", section: "Changes", label: "Fix", text: "<git diff>", content_type: "text/plain")
• Test output → doc-attach(render_as: "link", section: "Test Results", label: "Test run", text: "<output>", content_type: "text/plain")
• Session replay → doc-attach(render_as: "link", section: "Session Replays", label: "Stale filter on reload", url: "<viewer_url>")
• Validation screenshot → doc-attach(render_as: "image", section: "After", label: "Filter persists", artifact_id: "<live-view-screenshot id>")

When to close

When work is done and evidence is captured, call doc-close(status: "complete", summary: ...). If the work was incomplete, close as partial and explain in summary. If you never finished, abandoned.

There is no server-side score. Before closing, re-read the document (doc-read) and ask whether a human reviewer opening the URL cold would understand what changed, what was tested, and why. If not, attach what's missing.

Rules

1. Create at entry, not end. A doc started after the work captures nothing useful.
2. Seed structure up front. Pass a content template on doc-create. Editing after-the-fact is harder than starting with the right shape.
3. Pass doc_id to subagents. Evidence from subagents belongs in the same document.
4. Fill sections progressively. Don't batch all doc-update calls at the end.
5. Prefer text over base64_data for textual evidence (markdown, logs, JSON). It avoids token inflation.
6. Close with a useful summary. The summary appears in doc-list and the permanent snapshot.
7. Share the doc_url. Give it to the user when closing so they have the permanent link.

End-to-end transcript (bug fix)

User: Fix the session filter bug. Session: https://app.fullstory.com/ui/ABC/session/...

Agent:
1. doc-create(
     title: "Fix: session filter returns stale data",
     ref: "https://github.com/org/repo/issues/42",
     tags: ["session", "filter"],
     content: "<bug-fix template from this skill>"
   )
   → doc_id: "doc-abc123", doc_url: "https://..."

2. [session analysis subagent] review-open(session_url: ...) → observe filter resets
   doc-attach(
     doc_id: "doc-abc123", section: "Before", render_as: "link",
     url: <session_viewer_url>,
     label: "Session showing stale filter on page reload"
   )

3. [code exploration subagent] finds useSessionFilter.ts:47 — stale closure
   doc-update(
     doc_id: "doc-abc123",
     updates: [{old_str: "## Root Cause\n<!-- Why it broke -->",
                new_str: "## Root Cause\nStale closure in useSessionFilter.ts:47. The effect dep array omits `filterKey`, causing the filter to hold a reference to the initial empty state."}]
   )

4. [fix + test written]
   doc-attach(
     doc_id: "doc-abc123", section: "Changes", render_as: "link",
     text: <git diff output>, content_type: "text/plain",
     label: "Fix: add filterKey to dep array"
   )

5. [browser validation]
   doc-attach(
     doc_id: "doc-abc123", section: "After", render_as: "image",
     artifact_id: <live-view-screenshot id>,
     label: "Filter persists after reload"
   )

6. doc-close(doc_id: "doc-abc123", status: "complete",
             summary: "Fixed stale closure in session filter dep array. All tests pass. Browser confirms fix.")
   → doc_url: "https://..." (permanent)

User receives: "Fix complete. Proof document: https://..."

Gotchas

• Forgetting to doc-create at entry — you'll have no document to attach evidence to
• Seeding without content and then painting structure with doc-update — slower and more error-prone than seeding up front
• Using base64_data for text — use text instead to avoid ~33% inflation and wasted tokens
• Not sharing the doc_url — the user can't find the proof document without it

See Also

• subtext:shared — MCP conventions
• subtext:comments — inline session annotations (separate from proof docs)
• proof — workflow skill that integrates doc evidence capture with visual verification