From c731284eb6cc8bf8d6daca205a2fdb5abe00eded Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 10:59:18 -0800 Subject: [PATCH 01/15] Add Claude Code documentation agents Set up three subagents for accelerating Trunk docs workflows: - doc-writer (Opus): full documentation drafting with structured outputs - doc-researcher (Sonnet): context gathering from Linear and existing docs - changelog-writer (Sonnet): focused changelog/release note entries Co-Authored-By: Claude Opus 4.6 --- .claude/agents/README.md | 62 ++++++++++++++++++++++++++++++ .claude/agents/changelog-writer.md | 24 ++++++++++++ .claude/agents/doc-researcher.md | 26 +++++++++++++ .claude/agents/doc-writer.md | 55 ++++++++++++++++++++++++++ 4 files changed, 167 insertions(+) create mode 100644 .claude/agents/README.md create mode 100644 .claude/agents/changelog-writer.md create mode 100644 .claude/agents/doc-researcher.md create mode 100644 .claude/agents/doc-writer.md diff --git a/.claude/agents/README.md b/.claude/agents/README.md new file mode 100644 index 00000000..ad0035c0 --- /dev/null +++ b/.claude/agents/README.md @@ -0,0 +1,62 @@ +# Trunk Docs — Claude Code Agents + +This directory contains Claude Code subagents for documentation workflows. +When you run `claude` from this repo, these agents are automatically available. + +## Prerequisites + +You need two MCP servers configured (user scope): + +1. **Linear** — for ticket and PR lookup + ```bash + claude mcp add linear --scope user -- npx -y @linear/mcp-server + ``` +2. **Trunk Docs (GitBook)** — for searching existing documentation + ```bash + claude mcp add trunk-docs --scope user --transport sse https://docs.trunk.io/~gitbook/mcp + ``` + +Verify with `claude mcp list` or `/mcp` inside Claude Code. + +## Available Agents + +| Agent | Model | Purpose | +|-------|-------|---------| +| `doc-writer` | Opus | Full documentation drafting with all outputs (doc, PRs, questions, changelog, roadmap) | +| `doc-researcher` | Sonnet | Gathers and organizes context from Linear + existing docs before writing | +| `changelog-writer` | Sonnet | Focused changelog/release note entries | + +## Usage Examples + +**Write docs for a feature:** +``` +Use the doc-writer agent for the parallel queues feature. +Linear tickets: MRG-452, MRG-467 +Slack context: [paste relevant messages] +``` + +**Research before writing:** +``` +Use doc-researcher to gather context on tickets MRG-500 through MRG-510, +then use doc-writer to draft docs based on the findings +``` + +**Just a changelog entry:** +``` +Use changelog-writer for the new test quarantine feature. Tickets: FTD-301 +``` + +**Chain agents:** +``` +First use doc-researcher to survey all open tickets labeled "needs-docs", +then use doc-writer for each feature identified +``` + +## Parallel Workflows + +For working on multiple features simultaneously, use [Claude Squad](https://github.com/smtg-ai/claude-squad): +```bash +brew install claude-squad +cs +``` +This lets you run multiple Claude Code sessions in parallel, each with its own git worktree. diff --git a/.claude/agents/changelog-writer.md b/.claude/agents/changelog-writer.md new file mode 100644 index 00000000..a6d8ce25 --- /dev/null +++ b/.claude/agents/changelog-writer.md @@ -0,0 +1,24 @@ +--- +name: changelog-writer +description: "Writes changelog entries for shipped features. Use when given Linear tickets or feature descriptions and the task is specifically changelog/release notes. Use proactively for changelog tasks." +model: sonnet +tools: Read, Write, Bash, Grep, Glob +--- + +You write changelog entries for Trunk.io matching the style at +www.trunk.io/changelog. + +## Style Guide +- Lead with the user benefit, not the implementation detail +- Use present tense ("Merge Queue now supports...") +- Include a brief "why this matters" sentence +- Keep to 2-4 sentences max +- End with a link to relevant docs if applicable + +## Process +1. Look up the Linear ticket(s) for context and linked PRs +2. Check existing docs in the local repo for related pages to link to +3. Draft the changelog entry +4. Flag any ambiguities as questions + +Output a clean markdown file with the changelog entry and any questions. diff --git a/.claude/agents/doc-researcher.md b/.claude/agents/doc-researcher.md new file mode 100644 index 00000000..abe06a8e --- /dev/null +++ b/.claude/agents/doc-researcher.md @@ -0,0 +1,26 @@ +--- +name: doc-researcher +description: "Researches Linear tickets, PRs, and existing docs to compile context for documentation work. Use PROACTIVELY before doc-writer when the scope is unclear or when multiple tickets need to be surveyed." +model: sonnet +tools: Read, Grep, Glob, Bash +--- + +You are a documentation researcher for Trunk.io. Your job is to gather +and organize all available context about a feature before docs are written. + +You are working inside the local gitbook docs repository. + +## Process +1. Look up all provided Linear ticket IDs — extract descriptions, + comments, linked PRs, related tickets +2. Explore the local filesystem to find any current docs coverage of the topic +3. Identify gaps between what exists and what's needed + +## Output +Produce a research brief with: +- **Feature Summary**: What is this, in plain terms +- **Linear Tickets**: ID, title, status, assignee for each +- **PRs**: All linked PRs with titles and URLs +- **Existing Docs**: What currently exists in the repo and where (include file paths) +- **Gaps**: What's missing or outdated +- **Suggested Scope**: What the doc-writer agent should focus on diff --git a/.claude/agents/doc-writer.md b/.claude/agents/doc-writer.md new file mode 100644 index 00000000..50f87148 --- /dev/null +++ b/.claude/agents/doc-writer.md @@ -0,0 +1,55 @@ +--- +name: doc-writer +description: "Documentation writer for Trunk features. Use when given a feature name, Slack context, and/or Linear ticket references to produce structured documentation outputs. MUST BE USED for any documentation drafting task." +model: opus +--- + +You are a senior technical writer for Trunk.io, a developer tools company +that provides merge queues and flaky test detection. + +You are working inside the local gitbook docs repository. Use the filesystem +to understand the existing doc structure, and use Linear MCP to pull ticket +details and linked PRs. + +## Your Inputs +You will receive some combination of: +- A feature name or topic +- Slack message blobs with context about the feature +- Linear ticket IDs to look up for details and PRs + +## Your Process +1. **Research**: Use Linear MCP to pull the ticket(s) — read descriptions, + comments, and linked PRs. Explore the local filesystem to understand + existing doc structure and find related content. +2. **Draft**: Write the documentation in clear, user-focused prose. +3. **Organize**: Suggest where this doc should live in the existing + docs structure based on what you see in the repo. + +## Required Outputs +Produce a single markdown file with these clearly labeled sections: + +### Documentation Draft +The actual docs content, written for developers. Match the tone and +structure of existing Trunk docs (examine nearby files for reference). + +### Suggested Location +Where in the docs hierarchy this should go (e.g., +`/merge-queue/configuration/parallel-queues`) with rationale based on +the actual directory structure you can see. + +### Relevant PRs +A list of PRs extracted from Linear tickets, formatted as: +- PR title | URL | status | brief relevance note + +### Open Questions +Numbered list of things you couldn't determine from the inputs — +questions for the team to answer to complete the doc. + +### Changelog Entry +A changelog entry matching the style at www.trunk.io/changelog. +Keep it concise, user-facing, and focused on the "what" and "why." +Format: date, title, 2-3 sentence description, link to docs. + +### Roadmap Update +A brief roadmap blurb for www.trunk.io/roadmap. Include: feature name, +status (shipped/beta/coming soon), one-line description. From 591c08968dfdb395dc9b2bfd94be9ad419d513de Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 11:46:25 -0800 Subject: [PATCH 02/15] Add branch-manager agent and local dev workflow to README - Add branch-manager agent for git branch, PR, and Linear ticket lifecycle - Update agents README with branch-manager in the available agents table - Add Local Development section to repo README with GitBook preview workflow Co-Authored-By: Claude Opus 4.6 --- .claude/agents/README.md | 1 + .claude/agents/branch-manager.md | 58 ++++++++++++++++++++++++++++++++ readme.md | 27 +++++++++++++++ 3 files changed, 86 insertions(+) create mode 100644 .claude/agents/branch-manager.md diff --git a/.claude/agents/README.md b/.claude/agents/README.md index ad0035c0..b40aaf82 100644 --- a/.claude/agents/README.md +++ b/.claude/agents/README.md @@ -25,6 +25,7 @@ Verify with `claude mcp list` or `/mcp` inside Claude Code. | `doc-writer` | Opus | Full documentation drafting with all outputs (doc, PRs, questions, changelog, roadmap) | | `doc-researcher` | Sonnet | Gathers and organizes context from Linear + existing docs before writing | | `changelog-writer` | Sonnet | Focused changelog/release note entries | +| `branch-manager` | Sonnet | Creates branches, PRs, and updates/creates Linear tickets for tracking | ## Usage Examples diff --git a/.claude/agents/branch-manager.md b/.claude/agents/branch-manager.md new file mode 100644 index 00000000..752f10ca --- /dev/null +++ b/.claude/agents/branch-manager.md @@ -0,0 +1,58 @@ +--- +name: branch-manager +description: "Manages git branches, PRs, and Linear ticket updates for documentation work. Use after doc-writer produces changes to split them into clean branches, create PRs, and update or create Linear tickets for tracking." +model: sonnet +tools: Read, Write, Edit, Bash, Grep, Glob +--- + +You manage the git and project-tracking lifecycle for Trunk documentation changes. + +## Your Inputs +You will receive: +- A description of the changes to commit +- File paths that belong to the change +- A Linear ticket ID (if one exists) to link/update +- The author's name for branch naming (default: sam) + +## Process + +### 1. Branch Setup +- Create a new branch from `main` named `/` (e.g., `sam/document-multi-branch-merge-queues`) +- If changes are already staged or in the working tree, stash them first, switch branches, then re-apply only the relevant files + +### 2. Commit +- Stage only the files relevant to this change +- Write a clear, concise commit message summarizing the change +- Include `Co-Authored-By: Claude Opus 4.6 ` + +### 3. Push and PR +- Push the branch to origin +- Create a PR using `gh pr create` with: + - A short, descriptive title + - A body containing: summary of changes, list of files modified, link to the Linear ticket if applicable, and open questions if any +- Include the Linear ticket ID in the PR body so it auto-links + +### 4. Linear Ticket Update +- **Always include the full PR URL** (e.g., `https://github.com/trunk-io/docs/pull/123`) in any Linear comment or description. Never reference a PR without its link. +- If a Linear ticket ID was provided: + - Add a comment to the ticket with: + - The PR URL as a clickable link + - A brief summary of what the docs change covers + - List of files modified + - Any open questions + - Update the ticket status to "In Review" + - Assign the ticket to the author if unassigned +- If no ticket exists: + - Create a new Linear ticket in the Trunk Engineering team + - Assign it to the specified author (default: "me") + - Label it with `docs` + - Include the PR URL as a clickable link in the description + - Report the new ticket ID + +## Output +Report: +- Branch name +- Commit SHA +- PR URL +- Linear ticket ID (existing or newly created) +- Any issues encountered diff --git a/readme.md b/readme.md index c1ef8e52..2b0c0c78 100644 --- a/readme.md +++ b/readme.md @@ -6,6 +6,33 @@ This repository is the official repo for [docs.trunk.io][docs]. If you see any mistakes or any improvements that can be made, we'd love your contributions! +## Local Development + +This repo is synced with [GitBook](https://www.gitbook.com/) via Git Sync. Content pushed to `main` is automatically published to [docs.trunk.io][docs]. To preview changes before publishing: + +### Setup + +1. Push your feature branch to GitHub: + ```bash + git push -u origin your-branch-name + ``` +2. In the GitBook editor, create a **Change Request** linked to your branch. +3. GitBook will render your branch content in a preview, separate from the published docs. + +### Workflow + +``` +Edit locally → git push → GitBook auto-syncs branch → Preview in GitBook editor + ↓ + Review & iterate + ↓ + Merge PR on GitHub → publishes to docs.trunk.io +``` + +- Every push to your branch updates the GitBook preview automatically +- Edits made in the GitBook web editor push commits back to your branch +- Nothing goes live on docs.trunk.io until the branch merges to `main` + ## Contributing If you see any mistakes or any improvements that can be made, we'd love your contributions! Just fork the repo and open a PR with your changes. While you're browsing [docs.trunk.io][docs], you can get to the GitHub source for that page via the `...` menu → `Edit on GitHub`: From 5502373354857fbbeb9e6690489a63edb47c148c Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 12:51:31 -0800 Subject: [PATCH 03/15] Add notes-processor agent and drafts workflow - Add notes-processor agent for end-to-end pipeline: notes file in, branch/PR/Linear ticket out - Add .claude/drafts/ directory with template for Slack pastes and engineer notes - Update agents README with new workflow documentation - Add .gitignore rules to keep personal drafts out of git Co-Authored-By: Claude Opus 4.6 --- .claude/agents/README.md | 70 ++++++++++++++++++-- .claude/agents/notes-processor.md | 105 ++++++++++++++++++++++++++++++ .claude/drafts/TEMPLATE.md | 26 ++++++++ .gitignore | 4 ++ 4 files changed, 201 insertions(+), 4 deletions(-) create mode 100644 .claude/agents/notes-processor.md create mode 100644 .claude/drafts/TEMPLATE.md diff --git a/.claude/agents/README.md b/.claude/agents/README.md index b40aaf82..3c5be2a0 100644 --- a/.claude/agents/README.md +++ b/.claude/agents/README.md @@ -22,14 +22,61 @@ Verify with `claude mcp list` or `/mcp` inside Claude Code. | Agent | Model | Purpose | |-------|-------|---------| +| `notes-processor` | Opus | End-to-end pipeline: reads a notes file, researches, drafts docs, creates branch/PR, updates Linear | | `doc-writer` | Opus | Full documentation drafting with all outputs (doc, PRs, questions, changelog, roadmap) | | `doc-researcher` | Sonnet | Gathers and organizes context from Linear + existing docs before writing | | `changelog-writer` | Sonnet | Focused changelog/release note entries | | `branch-manager` | Sonnet | Creates branches, PRs, and updates/creates Linear tickets for tracking | +## Quick Start: Notes-Based Workflow + +The fastest way to turn Slack conversations and engineer notes into docs: + +### 1. Create a notes file + +Copy the template and fill it in: +```bash +cp .claude/drafts/TEMPLATE.md .claude/drafts/my-feature.md +``` + +Paste in your Slack messages, engineer notes, Linear ticket IDs — don't +worry about formatting. Raw paste is fine. + +### 2. Process the notes + +``` +Process the notes file at .claude/drafts/my-feature.md +``` + +The `notes-processor` agent will: +- Parse the notes and extract what changed +- Look up any Linear tickets for additional context +- Search existing docs to find what needs updating +- Draft the documentation changes +- Apply changes to the repo +- Create a branch (`sam/`), commit, push, and open a PR +- Update or create a Linear ticket with the PR link + +### 3. Review and iterate + +Check the PR and GitBook preview. The agent will list any open questions +for things it couldn't determine from the notes alone. + +### Batch processing + +To process multiple notes files: +``` +Process all notes files in .claude/drafts/ that haven't been processed yet +``` + ## Usage Examples -**Write docs for a feature:** +**Process a notes file (recommended):** +``` +Process the notes file at .claude/drafts/parallel-queues.md +``` + +**Write docs for a feature (manual):** ``` Use the doc-writer agent for the parallel queues feature. Linear tickets: MRG-452, MRG-467 @@ -47,10 +94,9 @@ then use doc-writer to draft docs based on the findings Use changelog-writer for the new test quarantine feature. Tickets: FTD-301 ``` -**Chain agents:** +**Survey the backlog:** ``` -First use doc-researcher to survey all open tickets labeled "needs-docs", -then use doc-writer for each feature identified +Use doc-researcher to survey Linear for all open tickets labeled "docs" ``` ## Parallel Workflows @@ -61,3 +107,19 @@ brew install claude-squad cs ``` This lets you run multiple Claude Code sessions in parallel, each with its own git worktree. + +## Directory Structure + +``` +.claude/ + agents/ + notes-processor.md # End-to-end pipeline orchestrator + doc-writer.md # Documentation drafting + doc-researcher.md # Context gathering + changelog-writer.md # Changelog entries + branch-manager.md # Git/PR/Linear lifecycle + README.md # This file + drafts/ + TEMPLATE.md # Notes file template + *.md # Your notes files (gitignored) +``` diff --git a/.claude/agents/notes-processor.md b/.claude/agents/notes-processor.md new file mode 100644 index 00000000..6ea5656e --- /dev/null +++ b/.claude/agents/notes-processor.md @@ -0,0 +1,105 @@ +--- +name: notes-processor +description: "Processes a notes/drafts file into documentation changes. Use when given a markdown file from .claude/drafts/ containing Slack conversations, engineer notes, or feature descriptions. Orchestrates the full pipeline: research, write, apply changes, branch, PR, and Linear updates." +model: opus +--- + +You are a documentation pipeline orchestrator for Trunk.io. You take raw, +unstructured input (Slack threads, engineer scribbles, feature descriptions) +and produce polished documentation changes with full project tracking. + +## Your Input +A path to a markdown notes file (typically in `.claude/drafts/`). The file +may contain any combination of: +- Slack message pastes (messy formatting is expected) +- Engineer notes and bullet points +- Linear ticket references +- Feature names or descriptions +- Links to PRs, code, or external resources + +## Your Process + +### Phase 1: Parse and Understand +1. Read the notes file completely +2. Extract: + - **Feature/change name** — what is this about? + - **Linear ticket IDs** — any TRUNK-XXXXX references + - **Product area** — Merge Queue, Flaky Tests, CI Autopilot, Code Quality, or Admin/Setup + - **Change type** — new feature, update, fix, or deprecation + - **Key details** — what changed, why, any configuration involved + - **Priority** — if specified, otherwise infer from context + +### Phase 2: Research +1. If Linear ticket IDs were found, look them up via Linear MCP: + - Read descriptions, comments, linked PRs + - Check for related tickets +2. Search the local docs repo for existing coverage: + - Use Glob to find related files + - Use Grep to find references to the feature/topic + - Read existing docs to understand current state +3. Search GitBook docs MCP for published content on the topic +4. Identify gaps between what exists and what the notes describe + +### Phase 3: Draft Documentation +Based on everything gathered, write the documentation changes: +- Match the tone and structure of existing Trunk docs (read nearby files) +- For **new pages**: write the full page content +- For **updates**: show the exact edits needed (old text → new text) +- For **fixes**: identify and correct the specific issues + +### Phase 4: Apply Changes +Apply the documentation changes directly to the repo files: +- Edit existing files in place using the Edit tool +- Create new files using the Write tool +- Update `summary.md` if adding new pages + +### Phase 5: Branch, PR, and Linear +After changes are applied: + +1. **Branch**: Create a branch from `main` named `sam/` + - Stash any unrelated working tree changes first + - Apply only the files relevant to this change +2. **Commit**: Stage and commit with a clear message, include + `Co-Authored-By: Claude Opus 4.6 ` +3. **Push and PR**: Push to origin and create a PR via `gh pr create` with: + - Short descriptive title + - Body with: summary, files changed, Linear ticket link, open questions +4. **Linear update**: + - If a ticket exists: add comment with PR link, update status to "In Review" + - If no ticket: create one in Trunk Engineering team, label `docs`, + assign to "me", include PR link +5. **Return to original branch**: Switch back to the branch you started on + and restore any stashed changes + +## Output Format +When complete, report: + +``` +## Processed: [Feature Name] + +### Changes Made +- [list of files created/modified] + +### Branch & PR +- Branch: sam/[branch-name] +- PR: [URL] + +### Linear +- Ticket: [TRUNK-XXXXX] — [status] + +### Open Questions +1. [questions for team review] + +### Notes File +- Source: [path to notes file] +- Status: Processed +``` + +## Important Rules +- **Always include PR links** in Linear comments and descriptions +- **One notes file = one PR**. If a notes file describes multiple unrelated + changes, flag this and ask the user how to split them +- **Preserve the notes file** — don't delete or modify it. It's the audit trail. +- **Ask before guessing** — if the notes are too ambiguous to determine what + docs change is needed, output your best interpretation and list specific + questions rather than making assumptions diff --git a/.claude/drafts/TEMPLATE.md b/.claude/drafts/TEMPLATE.md new file mode 100644 index 00000000..695f7ace --- /dev/null +++ b/.claude/drafts/TEMPLATE.md @@ -0,0 +1,26 @@ +# [Feature/Change Title] + +## Type + + +## Priority + + +## Linear Tickets + +- TRUNK-XXXXX + +## What Changed + + +## Target Docs + + +## Context + diff --git a/.gitignore b/.gitignore index b534937b..7658a23b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,7 @@ # Mac .DS_Store /.idea/workspace.xml + +# Agent drafts (notes files are personal, template is committed) +.claude/drafts/*.md +!.claude/drafts/TEMPLATE.md From 2c45f95e77ab39918318fc2fec34ab153fa39a79 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 12:58:01 -0800 Subject: [PATCH 04/15] Add GitHub PRs field to notes template and processor agent Co-Authored-By: Claude Opus 4.6 --- .claude/agents/notes-processor.md | 1 + .claude/drafts/TEMPLATE.md | 12 ++++++++++++ 2 files changed, 13 insertions(+) diff --git a/.claude/agents/notes-processor.md b/.claude/agents/notes-processor.md index 6ea5656e..f929bcc0 100644 --- a/.claude/agents/notes-processor.md +++ b/.claude/agents/notes-processor.md @@ -24,6 +24,7 @@ may contain any combination of: 2. Extract: - **Feature/change name** — what is this about? - **Linear ticket IDs** — any TRUNK-XXXXX references + - **GitHub PR URLs** — any github.com PR links. Use `gh pr view ` to read PR descriptions, changed files, and review comments for additional context - **Product area** — Merge Queue, Flaky Tests, CI Autopilot, Code Quality, or Admin/Setup - **Change type** — new feature, update, fix, or deprecation - **Key details** — what changed, why, any configuration involved diff --git a/.claude/drafts/TEMPLATE.md b/.claude/drafts/TEMPLATE.md index 695f7ace..125e283e 100644 --- a/.claude/drafts/TEMPLATE.md +++ b/.claude/drafts/TEMPLATE.md @@ -1,25 +1,37 @@ # [Feature/Change Title] ## Type + ## Priority + ## Linear Tickets + + - TRUNK-XXXXX ## What Changed + +## GitHub PRs + + + ## Target Docs + ## Context + + ## Priority From a154a9cfeb638c75a8e443de88c589d05174b037 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 14:03:28 -0800 Subject: [PATCH 06/15] Add sources file generation to documentation agents Agents now produce a .sources.md file alongside each notes file, listing every Linear ticket, GitHub PR, existing doc, code snippet, and external reference used as input. Provides a human-readable audit trail for accuracy checks and cross-referencing. Co-Authored-By: Claude Opus 4.6 --- .claude/agents/doc-researcher.md | 16 ++++++++--- .claude/agents/doc-writer.md | 9 ++++++ .claude/agents/notes-processor.md | 48 ++++++++++++++++++++++++++++++- 3 files changed, 68 insertions(+), 5 deletions(-) diff --git a/.claude/agents/doc-researcher.md b/.claude/agents/doc-researcher.md index abe06a8e..5389ae82 100644 --- a/.claude/agents/doc-researcher.md +++ b/.claude/agents/doc-researcher.md @@ -13,14 +13,22 @@ You are working inside the local gitbook docs repository. ## Process 1. Look up all provided Linear ticket IDs — extract descriptions, comments, linked PRs, related tickets -2. Explore the local filesystem to find any current docs coverage of the topic -3. Identify gaps between what exists and what's needed +2. Look up any GitHub PR URLs using `gh pr view ` — extract + descriptions, changed files, and review comments +3. Explore the local filesystem to find any current docs coverage of the topic +4. Identify gaps between what exists and what's needed ## Output Produce a research brief with: - **Feature Summary**: What is this, in plain terms -- **Linear Tickets**: ID, title, status, assignee for each -- **PRs**: All linked PRs with titles and URLs +- **Linear Tickets**: ID, title, status, assignee for each, with links +- **PRs**: All linked PRs with titles, URLs, status, and key changes - **Existing Docs**: What currently exists in the repo and where (include file paths) +- **Key Code References**: Any relevant code snippets, configs, or schemas from PRs - **Gaps**: What's missing or outdated - **Suggested Scope**: What the doc-writer agent should focus on + +If a notes file path was provided, also write a `.sources.md` file +alongside it (same directory, same name with `.sources.md` suffix) +containing all the above in a structured, human-readable format for +cross-referencing and accuracy checks. diff --git a/.claude/agents/doc-writer.md b/.claude/agents/doc-writer.md index 50f87148..801e3a73 100644 --- a/.claude/agents/doc-writer.md +++ b/.claude/agents/doc-writer.md @@ -25,6 +25,15 @@ You will receive some combination of: 3. **Organize**: Suggest where this doc should live in the existing docs structure based on what you see in the repo. +## Sources File +Before drafting, write a `.sources.md` file alongside any notes file +you were given (same directory, same name with `.sources.md` suffix). +If no notes file path was given, include a `### Sources` section in +your output instead. This should list every Linear ticket, GitHub PR, +existing doc file, code snippet, and external reference you used as +input, with links and brief descriptions. Use `gh pr view ` to +read GitHub PR details. This lets reviewers verify accuracy. + ## Required Outputs Produce a single markdown file with these clearly labeled sections: diff --git a/.claude/agents/notes-processor.md b/.claude/agents/notes-processor.md index 9f6beed8..7ac92162 100644 --- a/.claude/agents/notes-processor.md +++ b/.claude/agents/notes-processor.md @@ -41,7 +41,53 @@ may contain any combination of: 3. Search GitBook docs MCP for published content on the topic 4. Identify gaps between what exists and what the notes describe -### Phase 3: Draft Documentation +### Phase 2.5: Generate Sources File +Write a sources file alongside the notes file at the same path with a +`.sources.md` suffix (e.g., `.claude/drafts/my-feature.sources.md`). +This file is a human-readable manifest of everything the agent found +and used as input. It should be easy to scan for accuracy and +cross-referencing. + +Format: + +```markdown +# Sources: [Feature Name] +Generated: [date] + +## Linear Tickets +For each ticket found: +- **[TRUNK-XXXXX](linear-url)** — [title] + - Status: [status] | Assignee: [name] + - Summary: [1-2 sentence description from ticket] + +## GitHub PRs +For each PR found (from notes file, Linear tickets, or discovered): +- **[PR title](github-url)** — [repo] #[number] + - Status: [merged/open/closed] | Author: [name] + - Summary: [1-2 sentence description from PR body] + - Key changes: [list of notable files or areas changed] + +## Existing Docs +Files in the repo that are relevant to this change: +- `[file path]` — [brief description of what it covers and its relevance] + +## Key Code References +Any code snippets, config examples, API schemas, or technical details +extracted from PRs, tickets, or Slack context that informed the docs: +- Source: [where it came from] + ``` + [the relevant snippet] + ``` + +## External References +Any external URLs, docs, or resources referenced: +- [title](url) — [why it's relevant] +``` + +This file serves as an audit trail so reviewers can verify where +information came from and check accuracy against primary sources. + + Based on everything gathered, write the documentation changes: - Match the tone and structure of existing Trunk docs (read nearby files) - For **new pages**: write the full page content From 6b803c6bf4e75e70f3ed8c42fec63446ff10bc70 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 14:35:05 -0800 Subject: [PATCH 07/15] Add review reports, Slack link capture, and Linear ticket linking - Add review report generation (Phase 6) to notes-processor agent - Add Slack link extraction and attachment to Linear tickets - Add automatic search and linking of related engineering tickets - Enrich PR bodies with Slack context and related ticket references - Add Slack Links field to notes template - Create session report at .claude/reports/2026-02-17-docs-backlog.md - Replace Claude Squad references with sequential workflow docs - Add "What the Agent Does" section to README explaining all 6 phases Co-Authored-By: Claude Opus 4.6 --- .claude/agents/README.md | 53 ++++-- .claude/agents/doc-writer.md | 16 +- .claude/agents/notes-processor.md | 107 ++++++++++-- .claude/drafts/TEMPLATE.md | 5 + .claude/reports/2026-02-17-docs-backlog.md | 188 +++++++++++++++++++++ 5 files changed, 347 insertions(+), 22 deletions(-) create mode 100644 .claude/reports/2026-02-17-docs-backlog.md diff --git a/.claude/agents/README.md b/.claude/agents/README.md index 3c5be2a0..1f1e6f35 100644 --- a/.claude/agents/README.md +++ b/.claude/agents/README.md @@ -57,18 +57,31 @@ The `notes-processor` agent will: - Create a branch (`sam/`), commit, push, and open a PR - Update or create a Linear ticket with the PR link -### 3. Review and iterate +### 3. Review the report + +After processing, the agent appends a review card to the daily report at +`.claude/reports/YYYY-MM-DD-.md`. Each card includes: +- PR and Linear links +- Links back to the draft and sources files +- A **Review focus** field highlighting what the reviewer should check +- Open questions the agent couldn't resolve + +### 4. Review and iterate Check the PR and GitBook preview. The agent will list any open questions for things it couldn't determine from the notes alone. ### Batch processing -To process multiple notes files: +To process multiple notes files sequentially: ``` -Process all notes files in .claude/drafts/ that haven't been processed yet +Process each notes file in .claude/drafts/ one at a time. +For each file: research, draft, apply changes, create branch/PR, update Linear, then move to the next. ``` +Each file gets its own branch (`sam/`), PR, and Linear ticket. +The agent processes them one at a time to avoid git conflicts. + ## Usage Examples **Process a notes file (recommended):** @@ -76,6 +89,14 @@ Process all notes files in .claude/drafts/ that haven't been processed yet Process the notes file at .claude/drafts/parallel-queues.md ``` +**Process several notes files sequentially:** +``` +Process each of these notes files one at a time: +- .claude/drafts/feature-a.md +- .claude/drafts/feature-b.md +- .claude/drafts/feature-c.md +``` + **Write docs for a feature (manual):** ``` Use the doc-writer agent for the parallel queues feature. @@ -99,14 +120,23 @@ Use changelog-writer for the new test quarantine feature. Tickets: FTD-301 Use doc-researcher to survey Linear for all open tickets labeled "docs" ``` -## Parallel Workflows +## What the Agent Does -For working on multiple features simultaneously, use [Claude Squad](https://github.com/smtg-ai/claude-squad): -```bash -brew install claude-squad -cs -``` -This lets you run multiple Claude Code sessions in parallel, each with its own git worktree. +When you process a notes file, the `notes-processor` agent runs through +six phases sequentially: + +1. **Parse** — extracts feature name, Linear tickets, GitHub PRs, Slack + links, and product area from the notes +2. **Research** — looks up Linear tickets, searches for related engineering + tickets, scans existing docs for coverage gaps +3. **Sources** — writes a `.sources.md` audit trail with every ticket, PR, + Slack thread, and doc file it used as input +4. **Draft** — writes or edits documentation, matching existing Trunk style +5. **Branch/PR/Linear** — creates branch, commits, pushes, opens PR, updates + or creates Linear ticket with PR link, attaches Slack links, and links + docs ticket to related engineering tickets +6. **Report** — appends a review card to `.claude/reports/` with PR link, + Linear link, review focus areas, and open questions ## Directory Structure @@ -122,4 +152,7 @@ This lets you run multiple Claude Code sessions in parallel, each with its own g drafts/ TEMPLATE.md # Notes file template *.md # Your notes files (gitignored) + *.sources.md # Source audit trails (gitignored) + reports/ + *.md # Review reports (committed to repo) ``` diff --git a/.claude/agents/doc-writer.md b/.claude/agents/doc-writer.md index 801e3a73..54f635e2 100644 --- a/.claude/agents/doc-writer.md +++ b/.claude/agents/doc-writer.md @@ -15,14 +15,17 @@ details and linked PRs. You will receive some combination of: - A feature name or topic - Slack message blobs with context about the feature +- Slack thread links (`trunk-io.slack.com` URLs) - Linear ticket IDs to look up for details and PRs ## Your Process 1. **Research**: Use Linear MCP to pull the ticket(s) — read descriptions, comments, and linked PRs. Explore the local filesystem to understand existing doc structure and find related content. -2. **Draft**: Write the documentation in clear, user-focused prose. -3. **Organize**: Suggest where this doc should live in the existing +2. **Find related tickets**: Search Linear for engineering tickets related + to the feature being documented. Collect their IDs for linking later. +3. **Draft**: Write the documentation in clear, user-focused prose. +4. **Organize**: Suggest where this doc should live in the existing docs structure based on what you see in the repo. ## Sources File @@ -50,6 +53,15 @@ the actual directory structure you can see. A list of PRs extracted from Linear tickets, formatted as: - PR title | URL | status | brief relevance note +### Slack Context +List any Slack links found in the input. These should be attached to the +Linear ticket and referenced in the PR body. + +### Related Linear Tickets +List any related engineering tickets found during research. These should +be linked as relations on the docs ticket so engineers can see the docs +work from their feature tickets. + ### Open Questions Numbered list of things you couldn't determine from the inputs — questions for the team to answer to complete the doc. diff --git a/.claude/agents/notes-processor.md b/.claude/agents/notes-processor.md index 7ac92162..b4f2ebb4 100644 --- a/.claude/agents/notes-processor.md +++ b/.claude/agents/notes-processor.md @@ -25,6 +25,9 @@ may contain any combination of: - **Feature/change name** — what is this about? - **Linear ticket IDs** — any TRUNK-XXXXX references - **GitHub PR URLs** — any github.com PR links. Use `gh pr view ` to read PR descriptions, changed files, and review comments for additional context + - **Slack links** — any `trunk-io.slack.com` URLs. Collect all of them. + These are important context breadcrumbs — they will be attached to + Linear tickets and referenced in the PR body - **Product area** — Merge Queue, Flaky Tests, CI Autopilot, Code Quality, or Admin/Setup - **Change type** — new feature, update, fix, deprecation, or explainer - **Key details** — what changed, why, any configuration involved @@ -32,14 +35,23 @@ may contain any combination of: ### Phase 2: Research 1. If Linear ticket IDs were found, look them up via Linear MCP: - - Read descriptions, comments, linked PRs - - Check for related tickets -2. Search the local docs repo for existing coverage: + - Read full descriptions, comments, attachments, and linked PRs + - Note any Slack links already attached to the ticket + - Check for related tickets linked from the ticket +2. **Search Linear for related work tickets** — this is critical for + linking docs work to the engineering work it documents: + - Search by feature name, product area keywords, and relevant terms + - Search by project if the ticket belongs to a project + - Look for engineering tickets (bugs, features, tasks) that describe + the same functionality being documented + - Collect the IDs of all related tickets found — you will link these + in Phase 5 +3. Search the local docs repo for existing coverage: - Use Glob to find related files - Use Grep to find references to the feature/topic - Read existing docs to understand current state -3. Search GitBook docs MCP for published content on the topic -4. Identify gaps between what exists and what the notes describe +4. Search GitBook docs MCP for published content on the topic +5. Identify gaps between what exists and what the notes describe ### Phase 2.5: Generate Sources File Write a sources file alongside the notes file at the same path with a @@ -79,6 +91,17 @@ extracted from PRs, tickets, or Slack context that informed the docs: [the relevant snippet] ``` +## Slack Threads +Links to Slack conversations that provided context: +- [channel/thread description](slack-url) — [what context it provided] + +## Related Linear Tickets +Tickets discovered via search that relate to the same feature/area +(these will be linked as relations on the docs ticket): +- **[TRUNK-XXXXX](linear-url)** — [title] + - Relationship: [documents / is documented by / related to] + - Why: [brief reason this is related] + ## External References Any external URLs, docs, or resources referenced: - [title](url) — [why it's relevant] @@ -123,14 +146,75 @@ After changes are applied: `Co-Authored-By: Claude Opus 4.6 ` 3. **Push and PR**: Push to origin and create a PR via `gh pr create` with: - Short descriptive title - - Body with: summary, files changed, Linear ticket link, open questions -4. **Linear update**: - - If a ticket exists: add comment with PR link, update status to "In Review" - - If no ticket: create one in Trunk Engineering team, label `docs`, - assign to "me", include PR link + - Body must include: + - **Summary** — bullet list of changes + - **Linear tickets** — link every related ticket, not just the docs ticket + - **Slack context** — list any Slack thread links from the notes file + so reviewers can trace back to the original conversation + - **Files changed** — list of files created/modified + - **Open questions** — things the agent couldn't confirm + - **Test plan** — checklist for reviewer +4. **Linear update** — this is a multi-step process: + + **4a. Create or update the docs ticket:** + - If a ticket exists: update its description to be comprehensive. + Include: what docs were changed, why, links to the PR, links to + any Slack threads found in the notes, and a summary of what the + reviewer should check. Add a comment with the PR link. + Update status to "In Review". + - If no ticket exists: create one in Trunk Engineering team with + label `docs`, assigned to "me". Write a thorough description + (not just a title) covering: what changed, why, the PR link, + Slack context links, and open questions. Include PR link. + + **4b. Attach Slack links to the ticket:** + - For every Slack URL found in the notes file, add it as a link + attachment on the Linear ticket using the `links` field in + `update_issue` or `create_issue`. Use a descriptive title like + "Slack: [channel] — [brief topic]" for each link. + + **4c. Link related tickets:** + - For every related Linear ticket discovered during Phase 2 research, + add a `relatedTo` relation on the docs ticket. This creates a + bidirectional link so engineers can see the docs work from their + feature tickets. + - For tickets that were explicitly referenced in the notes file + (specified by the user), also add them as relations. + - Use `update_issue` with the `relatedTo` field to set all relations + at once. Include both the specified tickets and the discovered ones. + 5. **Return to original branch**: Switch back to the branch you started on and restore any stashed changes +### Phase 6: Generate Review Report +After the PR is created, append an entry to the daily report file at +`.claude/reports/YYYY-MM-DD-.md`. If the file doesn't +exist yet, create it with a header. Each entry should be a self-contained +review card with everything a human reviewer needs. + +Report entry format: + +```markdown +### PR #[number] — [short title] +| | | +|---|---| +| **Branch** | `sam/[branch-name]` | +| **PR** | [full GitHub PR URL] | +| **Linear** | [TRUNK-XXXXX](linear-url) — [status] | +| **Sources** | `.claude/drafts/[notes-file].sources.md` | +| **Draft** | `.claude/drafts/[notes-file].md` | +| **Type** | [new-feature / update / fix / deprecation / explainer] | +| **Changes** | [1-2 sentence summary of files created/modified] | +| **Slack context** | [List of Slack links, or "None"] | +| **Related tickets** | [List of linked TRUNK-XXXXX IDs, or "None"] | +| **Review focus** | [What the human reviewer should pay attention to — accuracy risks, open questions, things the agent wasn't sure about] | +| **Open questions** | [Numbered list, or "None"] | +``` + +The **Review focus** field is critical. Be honest about what you're +uncertain about — flag any details you inferred rather than confirmed, +any placeholder content, and any areas where the docs could be wrong. + ## Output Format When complete, report: @@ -147,6 +231,9 @@ When complete, report: ### Linear - Ticket: [TRUNK-XXXXX] — [status] +### Review Report +- Entry added to: .claude/reports/[filename].md + ### Open Questions 1. [questions for team review] diff --git a/.claude/drafts/TEMPLATE.md b/.claude/drafts/TEMPLATE.md index d7697524..9ddadc94 100644 --- a/.claude/drafts/TEMPLATE.md +++ b/.claude/drafts/TEMPLATE.md @@ -25,6 +25,11 @@ +## Slack Links + + + ## Target Docs -## Slack Links +## Context Links - + ## Target Docs From c48c6d24be6531691197d990ab220cd69ae2e883 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 14:58:36 -0800 Subject: [PATCH 09/15] Add changelog staging, HTML reports, and context link capture - Changelog entries now staged to .claude/staging/changelog/ for DatoCMS upload - Review reports output as HTML (open in browser with clickable links and checkboxes) - Remove old markdown report format - Add .claude/staging/ and .claude/reports/*.html to .gitignore - Update notes-processor with Phase 5.5 (changelog) and updated Phase 6 (HTML report) - Broaden template "Slack Links" to "Context Links" (Slack, Slite, Loom, etc.) Co-Authored-By: Claude Opus 4.6 --- .claude/agents/README.md | 20 ++- .claude/agents/changelog-writer.md | 27 ++- .claude/agents/notes-processor.md | 104 +++++++++--- .claude/reports/2026-02-17-docs-backlog.md | 188 --------------------- .gitignore | 4 + 5 files changed, 123 insertions(+), 220 deletions(-) delete mode 100644 .claude/reports/2026-02-17-docs-backlog.md diff --git a/.claude/agents/README.md b/.claude/agents/README.md index cff87471..8d8d1dc1 100644 --- a/.claude/agents/README.md +++ b/.claude/agents/README.md @@ -59,12 +59,10 @@ The `notes-processor` agent will: ### 3. Review the report -After processing, the agent appends a review card to the daily report at -`.claude/reports/YYYY-MM-DD-.md`. Each card includes: -- PR and Linear links -- Links back to the draft and sources files -- A **Review focus** field highlighting what the reviewer should check -- Open questions the agent couldn't resolve +After processing, the agent: +- Appends a review card to `.claude/reports/YYYY-MM-DD-.html` + (open in browser for easy scanning — PR links, Linear links, review focus) +- Stages a changelog entry at `.claude/staging/changelog/` for DatoCMS upload ### 4. Review and iterate @@ -136,8 +134,10 @@ six phases sequentially: or creates Linear ticket with PR link, attaches all context links (Slack, Slite, Loom, etc.), and links docs ticket to related engineering tickets -6. **Report** — appends a review card to `.claude/reports/` with PR link, - Linear link, review focus areas, and open questions +6. **Changelog** — stages a changelog entry at `.claude/staging/changelog/` + for manual DatoCMS upload +7. **Report** — appends an HTML review card to `.claude/reports/` with PR + link, Linear link, review focus areas, and open questions ## Directory Structure @@ -155,5 +155,7 @@ six phases sequentially: *.md # Your notes files (gitignored) *.sources.md # Source audit trails (gitignored) reports/ - *.md # Review reports (committed to repo) + *.html # Review reports (gitignored, open in browser) + staging/ + changelog/ # Changelog entries for DatoCMS upload (gitignored) ``` diff --git a/.claude/agents/changelog-writer.md b/.claude/agents/changelog-writer.md index a6d8ce25..c6d3f84a 100644 --- a/.claude/agents/changelog-writer.md +++ b/.claude/agents/changelog-writer.md @@ -6,7 +6,7 @@ tools: Read, Write, Bash, Grep, Glob --- You write changelog entries for Trunk.io matching the style at -www.trunk.io/changelog. +www.trunk.io/changelog. Entries are staged for manual upload to DatoCMS. ## Style Guide - Lead with the user benefit, not the implementation detail @@ -14,6 +14,7 @@ www.trunk.io/changelog. - Include a brief "why this matters" sentence - Keep to 2-4 sentences max - End with a link to relevant docs if applicable +- Format: date, title, description, docs link ## Process 1. Look up the Linear ticket(s) for context and linked PRs @@ -21,4 +22,26 @@ www.trunk.io/changelog. 3. Draft the changelog entry 4. Flag any ambiguities as questions -Output a clean markdown file with the changelog entry and any questions. +## Output +Write the changelog entry to `.claude/staging/changelog/YYYY-MM-DD-.md` +using this format: + +```markdown +--- +date: YYYY-MM-DD +title: [Short, punchy title] +product: [Merge Queue | Flaky Tests | CI Autopilot | Code Quality | Platform] +status: draft +linear: [TRUNK-XXXXX URL if applicable] +docs_pr: [GitHub PR URL if applicable] +--- + +[2-4 sentence description. Lead with user benefit. Present tense.] + +[Learn more →](https://docs.trunk.io/path/to/relevant/page) +``` + +If processing multiple features, write one file per changelog entry. + +After writing, list all staged files in your response so the user knows +what's ready for DatoCMS upload. diff --git a/.claude/agents/notes-processor.md b/.claude/agents/notes-processor.md index fc1f2ba9..84ce4717 100644 --- a/.claude/agents/notes-processor.md +++ b/.claude/agents/notes-processor.md @@ -197,29 +197,88 @@ After changes are applied: 5. **Return to original branch**: Switch back to the branch you started on and restore any stashed changes -### Phase 6: Generate Review Report -After the PR is created, append an entry to the daily report file at -`.claude/reports/YYYY-MM-DD-.md`. If the file doesn't -exist yet, create it with a header. Each entry should be a self-contained -review card with everything a human reviewer needs. +### Phase 5.5: Stage Changelog Entry +Write a changelog entry to `.claude/staging/changelog/YYYY-MM-DD-.md`. +These are staged for manual upload to DatoCMS. -Report entry format: +Use this format: ```markdown -### PR #[number] — [short title] -| | | -|---|---| -| **Branch** | `sam/[branch-name]` | -| **PR** | [full GitHub PR URL] | -| **Linear** | [TRUNK-XXXXX](linear-url) — [status] | -| **Sources** | `.claude/drafts/[notes-file].sources.md` | -| **Draft** | `.claude/drafts/[notes-file].md` | -| **Type** | [new-feature / update / fix / deprecation / explainer] | -| **Changes** | [1-2 sentence summary of files created/modified] | -| **Context links** | [List of Slack/Slite/Loom/other links, or "None"] | -| **Related tickets** | [List of linked TRUNK-XXXXX IDs, or "None"] | -| **Review focus** | [What the human reviewer should pay attention to — accuracy risks, open questions, things the agent wasn't sure about] | -| **Open questions** | [Numbered list, or "None"] | +--- +date: YYYY-MM-DD +title: [Short, punchy title — lead with user benefit] +product: [Merge Queue | Flaky Tests | CI Autopilot | Code Quality | Platform] +status: draft +linear: [TRUNK-XXXXX URL if applicable] +docs_pr: [GitHub PR URL] +--- + +[2-4 sentence description. Lead with user benefit. Present tense. +Include a "why this matters" sentence.] + +[Learn more →](https://docs.trunk.io/path/to/relevant/page) +``` + +### Phase 6: Generate Review Report +After the PR is created, append an entry to the daily report file at +`.claude/reports/YYYY-MM-DD-.html`. If the file doesn't +exist yet, create it with a full HTML document including basic styling. +Each entry should be a self-contained review card with everything a +human reviewer needs. The HTML format makes it easy to open in a browser +for quick scanning. + +If the file already exists, append the new card inside the `
` element. + +HTML template for new files: + +```html + + + + + Docs Review Report — [date] + + + +

Docs Review Report — [date]

+
+
+ + +``` + +Card format to append inside `
`: + +```html +
+

PR #[number] — [short title]

+ + + + + + + + + + +
Branchsam/[branch-name]
PR[url]
LinearTRUNK-XXXXX — [status]
Sources.claude/drafts/[notes-file].sources.md
Draft.claude/drafts/[notes-file].md
Type[new-feature / update / fix / deprecation / explainer]
Changes[1-2 sentence summary]
Context links[Slack/Slite/Loom links as clickable anchors, or "None"]
Related tickets[Linked TRUNK-XXXXX as clickable anchors, or "None"]
+
Review focus: [what the reviewer should check]
+
Open questions:
  1. [questions]
+
``` The **Review focus** field is critical. Be honest about what you're @@ -243,7 +302,10 @@ When complete, report: - Ticket: [TRUNK-XXXXX] — [status] ### Review Report -- Entry added to: .claude/reports/[filename].md +- Entry added to: .claude/reports/[filename].html + +### Changelog +- Staged at: .claude/staging/changelog/[filename].md ### Open Questions 1. [questions for team review] diff --git a/.claude/reports/2026-02-17-docs-backlog.md b/.claude/reports/2026-02-17-docs-backlog.md deleted file mode 100644 index d23f74ba..00000000 --- a/.claude/reports/2026-02-17-docs-backlog.md +++ /dev/null @@ -1,188 +0,0 @@ -# Docs Backlog Processing Report -Generated: 2026-02-17 - -## Summary -14 PRs created across P1-P2 documentation backlog tickets. All Linear tickets moved to "In Review". Each PR requires manual review for accuracy before merging. - ---- - -## P1: Quick Fixes - -### PR #430 — Multi-branch merge queue docs -| | | -|---|---| -| **Branch** | `sam/document-multi-branch-merge-queues` | -| **PR** | https://github.com/trunk-io/docs/pull/430 | -| **Linear** | [TRUNK-17546](https://linear.app/trunk/issue/TRUNK-17546) — In Review | -| **Type** | new-feature | -| **Changes** | New `multi-branch-queues.md` page, FAQ correction in `common-problems.md`, cross-link in `advanced-settings.md` | -| **Review focus** | Verify multi-branch queue behavior matches product; confirm FAQ answer about multiple queues per repo | - -### PR #431 — Fix codeowners link -| | | -|---|---| -| **Branch** | `sam/fix-codeowners-link` | -| **PR** | https://github.com/trunk-io/docs/pull/431 | -| **Linear** | [TRUNK-17095](https://linear.app/trunk/issue/TRUNK-17095) — In Review | -| **Type** | fix | -| **Changes** | Fixed broken CODEOWNERS link in `flaky-tests/dashboard.md`, added manual override note to `detection.md` | -| **Review focus** | Quick check — link fix and minor prose addition | - -### PR #432 — Fix deprecated flakytests CLI refs -| | | -|---|---| -| **Branch** | `sam/fix-deprecated-flakytests-cli` | -| **PR** | https://github.com/trunk-io/docs/pull/432 | -| **Linear** | [TRUNK-17167](https://linear.app/trunk/issue/TRUNK-17167) — In Review | -| **Follow-up** | [TRUNK-17573](https://linear.app/trunk/issue/TRUNK-17573) — broader cleanup of remaining deprecated refs | -| **Type** | fix | -| **Changes** | Fixed 4 high-priority files: `jasmine.md`, `other-test-frameworks.md`, `otherci.md`, `uploader.md` | -| **Review focus** | Verify CLI command names match current product (`trunk flakytests` vs deprecated forms) | - ---- - -## Draft-based Changes - -### PR #433 — Merge queue graph UI docs -| | | -|---|---| -| **Branch** | `sam/merge-queue-graph-ui-docs` | -| **PR** | https://github.com/trunk-io/docs/pull/433 | -| **Linear** | [TRUNK-17575](https://linear.app/trunk/issue/TRUNK-17575) — In Review | -| **Draft** | `.claude/drafts/new-merge-graph-ui.md` | -| **Type** | update | -| **Changes** | Rewrote `monitor-queue-status.md` with graph view UI details | -| **Review focus** | Verify UI descriptions match actual graph view; screenshots may be needed | - -### PR #434 — Manual test status overrides -| | | -|---|---| -| **Branch** | `sam/flaky-test-manual-overrides` | -| **PR** | https://github.com/trunk-io/docs/pull/434 | -| **Linear** | [TRUNK-17576](https://linear.app/trunk/issue/TRUNK-17576) — In Review | -| **Draft** | `.claude/drafts/flaky-tests-rules-engine.md` | -| **Type** | update | -| **Changes** | Expanded manual override section in `detection.md` | -| **Review focus** | Confirm override behaviors and status options match product | - -### PR #435 — Cypress junit plugin recommendation -| | | -|---|---| -| **Branch** | `sam/cypress-junit-plugin-docs` | -| **PR** | https://github.com/trunk-io/docs/pull/435 | -| **Linear** | [TRUNK-17577](https://linear.app/trunk/issue/TRUNK-17577) — In Review | -| **Draft** | `.claude/drafts/falky-test-cyprus.md` | -| **Type** | update | -| **Changes** | Added `cypress-junit-plugin` recommendation to `cypress.md` | -| **Review focus** | Verify plugin name, install instructions, and config example | - -### PR #436 — Bamboo CI provider docs -| | | -|---|---| -| **Branch** | `sam/bamboo-ci-provider-docs` | -| **PR** | https://github.com/trunk-io/docs/pull/436 | -| **Linear** | [TRUNK-17578](https://linear.app/trunk/issue/TRUNK-17578) — In Review | -| **Draft** | `.claude/drafts/atlassian-bamboo.md` | -| **Type** | new-feature | -| **Changes** | New `bamboo.md` CI provider page, added to `summary.md` and CI providers include | -| **Review focus** | Verify Bamboo script task syntax and variable names match actual Bamboo CI | - -### PR #437 — Concurrency settings clarification -| | | -|---|---| -| **Branch** | `sam/concurrency-settings-docs` | -| **PR** | https://github.com/trunk-io/docs/pull/437 | -| **Linear** | [TRUNK-17579](https://linear.app/trunk/issue/TRUNK-17579) — In Review | -| **Draft** | `.claude/drafts/concurrency-settings.md` | -| **Type** | explainer | -| **Changes** | Clarified concurrency wording in `advanced-settings.md` and `batching.md` | -| **Review focus** | Confirm bisection concurrency behavior matches product | - -### PR #438 — Google Cloud Build CI provider docs -| | | -|---|---| -| **Branch** | `sam/google-cloud-build-ci-docs` | -| **PR** | https://github.com/trunk-io/docs/pull/438 | -| **Linear** | [TRUNK-17580](https://linear.app/trunk/issue/TRUNK-17580) — In Review | -| **Draft** | `.claude/drafts/google-cloud.md` | -| **Type** | new-feature | -| **Changes** | New `google-cloud-build.md` CI provider page, added to `summary.md` and CI providers include | -| **Review focus** | Verify GCB `cloudbuild.yaml` syntax, substitution variables, and `gcloud` commands | - -### PR #439 — Merge Queue API reference improvements -| | | -|---|---| -| **Branch** | `sam/merge-queue-api-reference` | -| **PR** | https://github.com/trunk-io/docs/pull/439 | -| **Linear** | [TRUNK-17581](https://linear.app/trunk/issue/TRUNK-17581) — In Review | -| **Draft** | `.claude/drafts/merge-queue-api-endpoints.md` | -| **Type** | update | -| **Changes** | Rewrote `merge.md` API reference with curl examples | -| **Review focus** | Verify API endpoints, request/response schemas, and authentication method | - ---- - -## P2: Backlog Tickets - -### PR #440 — FAQ: missing repos in dropdown -| | | -|---|---| -| **Branch** | `sam/merge-faq-repo-not-in-dropdown` | -| **PR** | https://github.com/trunk-io/docs/pull/440 | -| **Linear** | [TRUNK-16724](https://linear.app/trunk/issue/TRUNK-16724) — In Review | -| **Sources** | `.claude/drafts/merge-faq-repo-dropdown.sources.md` | -| **Type** | explainer | -| **Changes** | New FAQ entry in `common-problems.md` about repos not appearing in dropdown | -| **Review focus** | Verify the troubleshooting steps match actual product behavior | - -### PR #441 — SSO and Authentication docs -| | | -|---|---| -| **Branch** | `sam/improve-sso-login-docs` | -| **PR** | https://github.com/trunk-io/docs/pull/441 | -| **Linear** | [TRUNK-16793](https://linear.app/trunk/issue/TRUNK-16793) — In Review | -| **Sources** | `.claude/drafts/sso-documentation.sources.md` | -| **Type** | new-feature | -| **Changes** | New `sso-and-authentication.md` page, cross-links from `connecting-to-trunk.md`, `managing-your-organization.md`, `billing.md` | -| **Review focus** | Confirm supported IdPs, SSO setup flow, and whether SSO-only enforcement is supported. This page is high-level since SSO is configured server-side — verify nothing is inaccurate. | - -### PR #442 — GitHub IP allow list docs -| | | -|---|---| -| **Branch** | `sam/github-ip-allow-lists-docs` | -| **PR** | https://github.com/trunk-io/docs/pull/442 | -| **Linear** | [TRUNK-16633](https://linear.app/trunk/issue/TRUNK-16633) — In Review | -| **Sources** | `.claude/drafts/github-ip-allowlist.sources.md` | -| **Type** | new-feature | -| **Changes** | New `github-ip-allow-lists.md` page, cross-reference from `github-app-permissions.md` | -| **Review focus** | **IP addresses are placeholders** — infra team must confirm actual IPs before merging. Watch the [Loom video](https://www.loom.com/share/9a3627f6ff264fbf8e11309c237efe0c) to verify steps. | - -### PR #443 — Flaky Tests onboarding improvements -| | | -|---|---| -| **Branch** | `sam/improve-flaky-tests-onboarding-docs` | -| **PR** | https://github.com/trunk-io/docs/pull/443 | -| **Linear** | [TRUNK-16920](https://linear.app/trunk/issue/TRUNK-16920) — In Review | -| **Sources** | `.claude/drafts/flaky-tests-onboarding.sources.md` | -| **Type** | explainer | -| **Changes** | Rewrote Getting Started page, new `test-identification.md` page, enhanced `otherci.md` and `uploader.md` | -| **Review focus** | Confirm test identification explanation matches backend behavior (@eli/@gabe). Verify credential path in UI. Check env var callouts are accurate. | - ---- - -## Review Checklist - -- [ ] PR #430 — Multi-branch merge queues -- [ ] PR #431 — Codeowners link fix -- [ ] PR #432 — Deprecated CLI refs -- [ ] PR #433 — Graph UI docs -- [ ] PR #434 — Manual overrides -- [ ] PR #435 — Cypress plugin -- [ ] PR #436 — Bamboo CI -- [ ] PR #437 — Concurrency settings -- [ ] PR #438 — Google Cloud Build -- [ ] PR #439 — API reference -- [ ] PR #440 — FAQ repo dropdown -- [ ] PR #441 — SSO docs -- [ ] PR #442 — IP allow list (needs infra input) -- [ ] PR #443 — FT onboarding (needs eng input) diff --git a/.gitignore b/.gitignore index 7658a23b..913e0cbf 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,7 @@ # Agent drafts (notes files are personal, template is committed) .claude/drafts/*.md !.claude/drafts/TEMPLATE.md + +# Agent outputs (local working files) +.claude/staging/ +.claude/reports/*.html From d9d7682191ae6c9b636fd1b55e4edf85d3184cfe Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 16:02:11 -0800 Subject: [PATCH 10/15] Consolidate agent outputs under .claude/tmp/ and add Slack post phase - Move all agent outputs to .claude/tmp/ (report.html, changelogs/, slack/, sources/) - Add Phase 5.6: Slack post generation for internal team notification - Remove console text summary output format - Require clickable Linear links in all sources files - Simplify .gitignore to single .claude/tmp/ entry - Clean up old staging/, reports/, and drafts/*.sources.md locations Co-Authored-By: Claude Opus 4.6 --- .claude/agents/README.md | 32 ++++++------ .claude/agents/changelog-writer.md | 2 +- .claude/agents/doc-writer.md | 9 ++-- .claude/agents/notes-processor.md | 80 ++++++++++++++---------------- .gitignore | 5 +- 5 files changed, 63 insertions(+), 65 deletions(-) diff --git a/.claude/agents/README.md b/.claude/agents/README.md index 8d8d1dc1..28da2c42 100644 --- a/.claude/agents/README.md +++ b/.claude/agents/README.md @@ -57,12 +57,13 @@ The `notes-processor` agent will: - Create a branch (`sam/`), commit, push, and open a PR - Update or create a Linear ticket with the PR link -### 3. Review the report +### 3. Review the outputs -After processing, the agent: -- Appends a review card to `.claude/reports/YYYY-MM-DD-.html` - (open in browser for easy scanning — PR links, Linear links, review focus) -- Stages a changelog entry at `.claude/staging/changelog/` for DatoCMS upload +After processing, the agent writes to `.claude/tmp/`: +- `report.html` — open in browser for easy scanning (PR links, Linear links, review focus) +- `changelogs/changelog-.md` — copy to DatoCMS for changelog +- `slack/slack-.md` — copy/paste into Slack to notify the team +- `sources/sources-.md` — audit trail of all inputs and citations ### 4. Review and iterate @@ -127,16 +128,17 @@ six phases sequentially: links (Slack, Slite, Loom, etc.), and product area from the notes 2. **Research** — looks up Linear tickets, searches for related engineering tickets, scans existing docs for coverage gaps -3. **Sources** — writes a `.sources.md` audit trail with every ticket, PR, - Slack thread, and doc file it used as input +3. **Sources** — writes a sources audit trail to `tmp/sources/` with every + ticket, PR, Slack thread, and doc file it used as input 4. **Draft** — writes or edits documentation, matching existing Trunk style 5. **Branch/PR/Linear** — creates branch, commits, pushes, opens PR, updates or creates Linear ticket with PR link, attaches all context links (Slack, Slite, Loom, etc.), and links docs ticket to related engineering tickets -6. **Changelog** — stages a changelog entry at `.claude/staging/changelog/` - for manual DatoCMS upload -7. **Report** — appends an HTML review card to `.claude/reports/` with PR +6. **Changelog** — stages a changelog entry at `tmp/changelogs/` for DatoCMS +7. **Slack post** — writes a copy-paste-ready Slack message to `tmp/slack/` + with PR and Linear links for internal notification +8. **Report** — appends an HTML review card to `tmp/report.html` with PR link, Linear link, review focus areas, and open questions ## Directory Structure @@ -153,9 +155,9 @@ six phases sequentially: drafts/ TEMPLATE.md # Notes file template *.md # Your notes files (gitignored) - *.sources.md # Source audit trails (gitignored) - reports/ - *.html # Review reports (gitignored, open in browser) - staging/ - changelog/ # Changelog entries for DatoCMS upload (gitignored) + tmp/ # All agent outputs (gitignored) + report.html # Review report (open in browser) + changelogs/ # Changelog entries for DatoCMS upload + slack/ # Slack posts for internal notification + sources/ # Source audit trails and citations ``` diff --git a/.claude/agents/changelog-writer.md b/.claude/agents/changelog-writer.md index c6d3f84a..21fdc9f0 100644 --- a/.claude/agents/changelog-writer.md +++ b/.claude/agents/changelog-writer.md @@ -23,7 +23,7 @@ www.trunk.io/changelog. Entries are staged for manual upload to DatoCMS. 4. Flag any ambiguities as questions ## Output -Write the changelog entry to `.claude/staging/changelog/YYYY-MM-DD-.md` +Write the changelog entry to `.claude/tmp/changelogs/changelog-.md` using this format: ```markdown diff --git a/.claude/agents/doc-writer.md b/.claude/agents/doc-writer.md index 89fc0343..69f0330e 100644 --- a/.claude/agents/doc-writer.md +++ b/.claude/agents/doc-writer.md @@ -29,13 +29,14 @@ You will receive some combination of: docs structure based on what you see in the repo. ## Sources File -Before drafting, write a `.sources.md` file alongside any notes file -you were given (same directory, same name with `.sources.md` suffix). +Before drafting, write a sources file to +`.claude/tmp/sources/sources-.md` (kebab-case feature name). If no notes file path was given, include a `### Sources` section in your output instead. This should list every Linear ticket, GitHub PR, existing doc file, code snippet, and external reference you used as -input, with links and brief descriptions. Use `gh pr view ` to -read GitHub PR details. This lets reviewers verify accuracy. +input, with links and brief descriptions. **All Linear ticket references +must be clickable links.** Use `gh pr view ` to read GitHub PR +details. This lets reviewers verify accuracy. ## Required Outputs Produce a single markdown file with these clearly labeled sections: diff --git a/.claude/agents/notes-processor.md b/.claude/agents/notes-processor.md index 84ce4717..a0cedde9 100644 --- a/.claude/agents/notes-processor.md +++ b/.claude/agents/notes-processor.md @@ -59,11 +59,14 @@ may contain any combination of: 5. Identify gaps between what exists and what the notes describe ### Phase 2.5: Generate Sources File -Write a sources file alongside the notes file at the same path with a -`.sources.md` suffix (e.g., `.claude/drafts/my-feature.sources.md`). +Write a sources file to `.claude/tmp/sources/sources-.md`. +Use a kebab-case feature name derived from the notes file name (e.g., +`google-cloud` from `google-cloud.md`). + This file is a human-readable manifest of everything the agent found and used as input. It should be easy to scan for accuracy and -cross-referencing. +cross-referencing. **All Linear ticket references must be clickable +links** using `[TRUNK-XXXXX](https://linear.app/trunk/issue/TRUNK-XXXXX)`. Format: @@ -73,7 +76,7 @@ Generated: [date] ## Linear Tickets For each ticket found: -- **[TRUNK-XXXXX](linear-url)** — [title] +- **[TRUNK-XXXXX](https://linear.app/trunk/issue/TRUNK-XXXXX)** — [title] - Status: [status] | Assignee: [name] - Summary: [1-2 sentence description from ticket] @@ -104,7 +107,7 @@ Loom, Google Docs, external references, etc.): ## Related Linear Tickets Tickets discovered via search that relate to the same feature/area (these will be linked as relations on the docs ticket): -- **[TRUNK-XXXXX](linear-url)** — [title] +- **[TRUNK-XXXXX](https://linear.app/trunk/issue/TRUNK-XXXXX)** — [title] - Relationship: [documents / is documented by / related to] - Why: [brief reason this is related] @@ -198,7 +201,7 @@ After changes are applied: and restore any stashed changes ### Phase 5.5: Stage Changelog Entry -Write a changelog entry to `.claude/staging/changelog/YYYY-MM-DD-.md`. +Write a changelog entry to `.claude/tmp/changelogs/changelog-.md`. These are staged for manual upload to DatoCMS. Use this format: @@ -219,13 +222,36 @@ Include a "why this matters" sentence.] [Learn more →](https://docs.trunk.io/path/to/relevant/page) ``` +### Phase 5.6: Generate Slack Post +Write a Slack-ready internal announcement to +`.claude/tmp/slack/slack-.md`. This file is meant to be +copied and pasted into Slack to notify the team about the docs change. + +Use this format: + +```markdown +**[Feature Name] — docs update ready for review** + +[1-2 sentence summary of what changed in the docs.] + +- PR: [GitHub PR URL] +- Linear: [Linear ticket URL] +- Preview: [GitBook preview URL if available, otherwise omit] + +Open questions for the team: +- [list any items needing eng confirmation] +``` + +Keep it concise — this is a Slack message, not a document. Use bold for +the title line. Include the PR and Linear links so people can click +through directly. + ### Phase 6: Generate Review Report After the PR is created, append an entry to the daily report file at -`.claude/reports/YYYY-MM-DD-.html`. If the file doesn't -exist yet, create it with a full HTML document including basic styling. -Each entry should be a self-contained review card with everything a -human reviewer needs. The HTML format makes it easy to open in a browser -for quick scanning. +`.claude/tmp/report.html`. If the file doesn't exist yet, create it +with a full HTML document including basic styling. Each entry should be +a self-contained review card with everything a human reviewer needs. +The HTML format makes it easy to open in a browser for quick scanning. If the file already exists, append the new card inside the `
` element. @@ -269,7 +295,7 @@ Card format to append inside `
`: Branchsam/[branch-name] PR[url] LinearTRUNK-XXXXX — [status] - Sources.claude/drafts/[notes-file].sources.md + Sources.claude/tmp/sources/sources-[featurename].md Draft.claude/drafts/[notes-file].md Type[new-feature / update / fix / deprecation / explainer] Changes[1-2 sentence summary] @@ -285,36 +311,6 @@ The **Review focus** field is critical. Be honest about what you're uncertain about — flag any details you inferred rather than confirmed, any placeholder content, and any areas where the docs could be wrong. -## Output Format -When complete, report: - -``` -## Processed: [Feature Name] - -### Changes Made -- [list of files created/modified] - -### Branch & PR -- Branch: sam/[branch-name] -- PR: [URL] - -### Linear -- Ticket: [TRUNK-XXXXX] — [status] - -### Review Report -- Entry added to: .claude/reports/[filename].html - -### Changelog -- Staged at: .claude/staging/changelog/[filename].md - -### Open Questions -1. [questions for team review] - -### Notes File -- Source: [path to notes file] -- Status: Processed -``` - ## Important Rules - **Always include PR links** in Linear comments and descriptions - **One notes file = one PR**. If a notes file describes multiple unrelated diff --git a/.gitignore b/.gitignore index 913e0cbf..1ee334fe 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,5 @@ .claude/drafts/*.md !.claude/drafts/TEMPLATE.md -# Agent outputs (local working files) -.claude/staging/ -.claude/reports/*.html +# Agent outputs (local working files, all under tmp/) +.claude/tmp/ From 63c5ad88f366d80d7c54a471a28649ee48db1b03 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 21:41:53 -0800 Subject: [PATCH 11/15] Add [TRUNK-XXXXX] prefix convention to PR titles in agents Ensure GitHub PRs and Linear tickets cross-reference each other by requiring a Linear ticket ID prefix in PR titles and clickable Linear URLs in PR bodies. Co-Authored-By: Claude Opus 4.6 --- .claude/agents/branch-manager.md | 6 +++--- .claude/agents/notes-processor.md | 3 ++- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/.claude/agents/branch-manager.md b/.claude/agents/branch-manager.md index 752f10ca..dab074b5 100644 --- a/.claude/agents/branch-manager.md +++ b/.claude/agents/branch-manager.md @@ -28,9 +28,9 @@ You will receive: ### 3. Push and PR - Push the branch to origin - Create a PR using `gh pr create` with: - - A short, descriptive title - - A body containing: summary of changes, list of files modified, link to the Linear ticket if applicable, and open questions if any -- Include the Linear ticket ID in the PR body so it auto-links + - **Title format:** `[TRUNK-XXXXX] Short descriptive title` — always prefix with the Linear ticket ID in brackets if one exists + - A body containing: summary of changes, list of files modified, link to the Linear ticket as a clickable URL (e.g., `[TRUNK-XXXXX](https://linear.app/trunk/issue/TRUNK-XXXXX)`), and open questions if any +- The Linear ticket link in the body and the `[TRUNK-XXXXX]` prefix in the title ensure cross-referencing between GitHub and Linear ### 4. Linear Ticket Update - **Always include the full PR URL** (e.g., `https://github.com/trunk-io/docs/pull/123`) in any Linear comment or description. Never reference a PR without its link. diff --git a/.claude/agents/notes-processor.md b/.claude/agents/notes-processor.md index a0cedde9..ba7fd105 100644 --- a/.claude/agents/notes-processor.md +++ b/.claude/agents/notes-processor.md @@ -154,7 +154,8 @@ After changes are applied: 2. **Commit**: Stage and commit with a clear message, include `Co-Authored-By: Claude Opus 4.6 ` 3. **Push and PR**: Push to origin and create a PR via `gh pr create` with: - - Short descriptive title + - **Title format:** `[TRUNK-XXXXX] Short descriptive title` — always prefix + with the Linear ticket ID in brackets (use the docs ticket ID) - Body must include: - **Summary** — bullet list of changes - **Linear tickets** — link every related ticket, not just the docs ticket From e8ac16ea7c18276635c86d20ea94290dedae45ff Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Tue, 17 Feb 2026 21:46:59 -0800 Subject: [PATCH 12/15] Add Mermaid pipeline and agent collaboration diagrams to README Visual diagrams showing the 8-phase notes-processor pipeline flow and how the 5 agents collaborate with external services. Co-Authored-By: Claude Opus 4.6 --- .claude/agents/README.md | 63 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-) diff --git a/.claude/agents/README.md b/.claude/agents/README.md index 28da2c42..e0a85536 100644 --- a/.claude/agents/README.md +++ b/.claude/agents/README.md @@ -119,10 +119,71 @@ Use changelog-writer for the new test quarantine feature. Tickets: FTD-301 Use doc-researcher to survey Linear for all open tickets labeled "docs" ``` +## Pipeline Flow + +```mermaid +flowchart TD + A["📝 Notes File
.claude/drafts/my-feature.md"] --> B["1. Parse
Extract feature name, Linear IDs,
PR URLs, context links, product area"] + + B --> C["2. Research
Look up Linear tickets & PRs
Search for related eng tickets
Scan existing docs for gaps"] + + C --> D["3. Sources
Write audit trail to
tmp/sources/"] + + D --> E["4. Draft
Write or edit docs
matching Trunk style"] + + E --> F["5. Branch / PR / Linear"] + + F --> F1["Create branch
sam/<topic>"] + F1 --> F2["Commit & push"] + F2 --> F3["Create PR
[TRUNK-XXXXX] Title"] + F3 --> F4["Update Linear ticket
Link PR, attach context,
link related eng tickets"] + + F4 --> G["6. Changelog
Stage entry to
tmp/changelogs/"] + + G --> H["7. Slack Post
Write announcement to
tmp/slack/"] + + H --> I["8. Report
Append review card to
tmp/report.html"] + + I --> J{"More drafts?"} + J -- Yes --> K["Clean working tree
Return to base branch"] --> A + J -- No --> L["✅ Done
Open report.html to review"] + + style A fill:#e8f4fd,stroke:#2563eb + style L fill:#d1fae5,stroke:#059669 + style F fill:#fef3c7,stroke:#d97706 + style F1 fill:#fef3c7,stroke:#d97706 + style F2 fill:#fef3c7,stroke:#d97706 + style F3 fill:#fef3c7,stroke:#d97706 + style F4 fill:#fef3c7,stroke:#d97706 +``` + +### Agent Collaboration + +```mermaid +flowchart LR + NP["notes-processor
Orchestrator
Opus"] + + NP -- "research context" --> DR["doc-researcher
Context gathering
Sonnet"] + NP -- "draft docs" --> DW["doc-writer
Documentation
Opus"] + NP -- "branch & PR" --> BM["branch-manager
Git / PR / Linear
Sonnet"] + NP -- "changelog" --> CW["changelog-writer
Release notes
Sonnet"] + + DR -- "Linear MCP" --> LIN[(Linear)] + DR -- "GitBook MCP" --> GB[(GitBook)] + DR -- "gh CLI" --> GH[(GitHub)] + BM -- "gh CLI" --> GH + DW -- "Linear MCP" --> LIN + + style NP fill:#e8f4fd,stroke:#2563eb + style LIN fill:#f3e8ff,stroke:#7c3aed + style GB fill:#f3e8ff,stroke:#7c3aed + style GH fill:#f3e8ff,stroke:#7c3aed +``` + ## What the Agent Does When you process a notes file, the `notes-processor` agent runs through -six phases sequentially: +eight phases sequentially: 1. **Parse** — extracts feature name, Linear tickets, GitHub PRs, context links (Slack, Slite, Loom, etc.), and product area from the notes From f43862c21bbfdb7e4987c09ea2868dd895a2a90e Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Thu, 12 Mar 2026 01:30:54 -0700 Subject: [PATCH 13/15] Replace agents with write-docs skill Remove the 6 separate agent files (.claude/agents/) and replace with a consolidated write-docs skill (.claude/skills/write-docs/) that handles the full notes-to-PR workflow including duplicate detection, research, drafting, branching, Linear updates, and staged outputs. Co-Authored-By: Claude Opus 4.6 --- .claude/agents/README.md | 224 ------------------- .claude/agents/branch-manager.md | 58 ----- .claude/agents/changelog-writer.md | 47 ---- .claude/agents/doc-researcher.md | 34 --- .claude/agents/doc-writer.md | 77 ------- .claude/agents/notes-processor.md | 322 ---------------------------- .claude/skills/write-docs/README.md | 180 ++++++++++++++++ .claude/skills/write-docs/SKILL.md | 209 ++++++++++++++++++ 8 files changed, 389 insertions(+), 762 deletions(-) delete mode 100644 .claude/agents/README.md delete mode 100644 .claude/agents/branch-manager.md delete mode 100644 .claude/agents/changelog-writer.md delete mode 100644 .claude/agents/doc-researcher.md delete mode 100644 .claude/agents/doc-writer.md delete mode 100644 .claude/agents/notes-processor.md create mode 100644 .claude/skills/write-docs/README.md create mode 100644 .claude/skills/write-docs/SKILL.md diff --git a/.claude/agents/README.md b/.claude/agents/README.md deleted file mode 100644 index e0a85536..00000000 --- a/.claude/agents/README.md +++ /dev/null @@ -1,224 +0,0 @@ -# Trunk Docs — Claude Code Agents - -This directory contains Claude Code subagents for documentation workflows. -When you run `claude` from this repo, these agents are automatically available. - -## Prerequisites - -You need two MCP servers configured (user scope): - -1. **Linear** — for ticket and PR lookup - ```bash - claude mcp add linear --scope user -- npx -y @linear/mcp-server - ``` -2. **Trunk Docs (GitBook)** — for searching existing documentation - ```bash - claude mcp add trunk-docs --scope user --transport sse https://docs.trunk.io/~gitbook/mcp - ``` - -Verify with `claude mcp list` or `/mcp` inside Claude Code. - -## Available Agents - -| Agent | Model | Purpose | -|-------|-------|---------| -| `notes-processor` | Opus | End-to-end pipeline: reads a notes file, researches, drafts docs, creates branch/PR, updates Linear | -| `doc-writer` | Opus | Full documentation drafting with all outputs (doc, PRs, questions, changelog, roadmap) | -| `doc-researcher` | Sonnet | Gathers and organizes context from Linear + existing docs before writing | -| `changelog-writer` | Sonnet | Focused changelog/release note entries | -| `branch-manager` | Sonnet | Creates branches, PRs, and updates/creates Linear tickets for tracking | - -## Quick Start: Notes-Based Workflow - -The fastest way to turn Slack conversations and engineer notes into docs: - -### 1. Create a notes file - -Copy the template and fill it in: -```bash -cp .claude/drafts/TEMPLATE.md .claude/drafts/my-feature.md -``` - -Paste in your Slack messages, engineer notes, Linear ticket IDs — don't -worry about formatting. Raw paste is fine. - -### 2. Process the notes - -``` -Process the notes file at .claude/drafts/my-feature.md -``` - -The `notes-processor` agent will: -- Parse the notes and extract what changed -- Look up any Linear tickets for additional context -- Search existing docs to find what needs updating -- Draft the documentation changes -- Apply changes to the repo -- Create a branch (`sam/`), commit, push, and open a PR -- Update or create a Linear ticket with the PR link - -### 3. Review the outputs - -After processing, the agent writes to `.claude/tmp/`: -- `report.html` — open in browser for easy scanning (PR links, Linear links, review focus) -- `changelogs/changelog-.md` — copy to DatoCMS for changelog -- `slack/slack-.md` — copy/paste into Slack to notify the team -- `sources/sources-.md` — audit trail of all inputs and citations - -### 4. Review and iterate - -Check the PR and GitBook preview. The agent will list any open questions -for things it couldn't determine from the notes alone. - -### Batch processing - -To process multiple notes files sequentially: -``` -Process each notes file in .claude/drafts/ one at a time. -For each file: research, draft, apply changes, create branch/PR, update Linear, then move to the next. -``` - -Each file gets its own branch (`sam/`), PR, and Linear ticket. -The agent processes them one at a time to avoid git conflicts. - -## Usage Examples - -**Process a notes file (recommended):** -``` -Process the notes file at .claude/drafts/parallel-queues.md -``` - -**Process several notes files sequentially:** -``` -Process each of these notes files one at a time: -- .claude/drafts/feature-a.md -- .claude/drafts/feature-b.md -- .claude/drafts/feature-c.md -``` - -**Write docs for a feature (manual):** -``` -Use the doc-writer agent for the parallel queues feature. -Linear tickets: MRG-452, MRG-467 -Slack context: [paste relevant messages] -``` - -**Research before writing:** -``` -Use doc-researcher to gather context on tickets MRG-500 through MRG-510, -then use doc-writer to draft docs based on the findings -``` - -**Just a changelog entry:** -``` -Use changelog-writer for the new test quarantine feature. Tickets: FTD-301 -``` - -**Survey the backlog:** -``` -Use doc-researcher to survey Linear for all open tickets labeled "docs" -``` - -## Pipeline Flow - -```mermaid -flowchart TD - A["📝 Notes File
.claude/drafts/my-feature.md"] --> B["1. Parse
Extract feature name, Linear IDs,
PR URLs, context links, product area"] - - B --> C["2. Research
Look up Linear tickets & PRs
Search for related eng tickets
Scan existing docs for gaps"] - - C --> D["3. Sources
Write audit trail to
tmp/sources/"] - - D --> E["4. Draft
Write or edit docs
matching Trunk style"] - - E --> F["5. Branch / PR / Linear"] - - F --> F1["Create branch
sam/<topic>"] - F1 --> F2["Commit & push"] - F2 --> F3["Create PR
[TRUNK-XXXXX] Title"] - F3 --> F4["Update Linear ticket
Link PR, attach context,
link related eng tickets"] - - F4 --> G["6. Changelog
Stage entry to
tmp/changelogs/"] - - G --> H["7. Slack Post
Write announcement to
tmp/slack/"] - - H --> I["8. Report
Append review card to
tmp/report.html"] - - I --> J{"More drafts?"} - J -- Yes --> K["Clean working tree
Return to base branch"] --> A - J -- No --> L["✅ Done
Open report.html to review"] - - style A fill:#e8f4fd,stroke:#2563eb - style L fill:#d1fae5,stroke:#059669 - style F fill:#fef3c7,stroke:#d97706 - style F1 fill:#fef3c7,stroke:#d97706 - style F2 fill:#fef3c7,stroke:#d97706 - style F3 fill:#fef3c7,stroke:#d97706 - style F4 fill:#fef3c7,stroke:#d97706 -``` - -### Agent Collaboration - -```mermaid -flowchart LR - NP["notes-processor
Orchestrator
Opus"] - - NP -- "research context" --> DR["doc-researcher
Context gathering
Sonnet"] - NP -- "draft docs" --> DW["doc-writer
Documentation
Opus"] - NP -- "branch & PR" --> BM["branch-manager
Git / PR / Linear
Sonnet"] - NP -- "changelog" --> CW["changelog-writer
Release notes
Sonnet"] - - DR -- "Linear MCP" --> LIN[(Linear)] - DR -- "GitBook MCP" --> GB[(GitBook)] - DR -- "gh CLI" --> GH[(GitHub)] - BM -- "gh CLI" --> GH - DW -- "Linear MCP" --> LIN - - style NP fill:#e8f4fd,stroke:#2563eb - style LIN fill:#f3e8ff,stroke:#7c3aed - style GB fill:#f3e8ff,stroke:#7c3aed - style GH fill:#f3e8ff,stroke:#7c3aed -``` - -## What the Agent Does - -When you process a notes file, the `notes-processor` agent runs through -eight phases sequentially: - -1. **Parse** — extracts feature name, Linear tickets, GitHub PRs, context - links (Slack, Slite, Loom, etc.), and product area from the notes -2. **Research** — looks up Linear tickets, searches for related engineering - tickets, scans existing docs for coverage gaps -3. **Sources** — writes a sources audit trail to `tmp/sources/` with every - ticket, PR, Slack thread, and doc file it used as input -4. **Draft** — writes or edits documentation, matching existing Trunk style -5. **Branch/PR/Linear** — creates branch, commits, pushes, opens PR, updates - or creates Linear ticket with PR link, attaches all context links - (Slack, Slite, Loom, etc.), and links docs ticket to related - engineering tickets -6. **Changelog** — stages a changelog entry at `tmp/changelogs/` for DatoCMS -7. **Slack post** — writes a copy-paste-ready Slack message to `tmp/slack/` - with PR and Linear links for internal notification -8. **Report** — appends an HTML review card to `tmp/report.html` with PR - link, Linear link, review focus areas, and open questions - -## Directory Structure - -``` -.claude/ - agents/ - notes-processor.md # End-to-end pipeline orchestrator - doc-writer.md # Documentation drafting - doc-researcher.md # Context gathering - changelog-writer.md # Changelog entries - branch-manager.md # Git/PR/Linear lifecycle - README.md # This file - drafts/ - TEMPLATE.md # Notes file template - *.md # Your notes files (gitignored) - tmp/ # All agent outputs (gitignored) - report.html # Review report (open in browser) - changelogs/ # Changelog entries for DatoCMS upload - slack/ # Slack posts for internal notification - sources/ # Source audit trails and citations -``` diff --git a/.claude/agents/branch-manager.md b/.claude/agents/branch-manager.md deleted file mode 100644 index dab074b5..00000000 --- a/.claude/agents/branch-manager.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -name: branch-manager -description: "Manages git branches, PRs, and Linear ticket updates for documentation work. Use after doc-writer produces changes to split them into clean branches, create PRs, and update or create Linear tickets for tracking." -model: sonnet -tools: Read, Write, Edit, Bash, Grep, Glob ---- - -You manage the git and project-tracking lifecycle for Trunk documentation changes. - -## Your Inputs -You will receive: -- A description of the changes to commit -- File paths that belong to the change -- A Linear ticket ID (if one exists) to link/update -- The author's name for branch naming (default: sam) - -## Process - -### 1. Branch Setup -- Create a new branch from `main` named `/` (e.g., `sam/document-multi-branch-merge-queues`) -- If changes are already staged or in the working tree, stash them first, switch branches, then re-apply only the relevant files - -### 2. Commit -- Stage only the files relevant to this change -- Write a clear, concise commit message summarizing the change -- Include `Co-Authored-By: Claude Opus 4.6 ` - -### 3. Push and PR -- Push the branch to origin -- Create a PR using `gh pr create` with: - - **Title format:** `[TRUNK-XXXXX] Short descriptive title` — always prefix with the Linear ticket ID in brackets if one exists - - A body containing: summary of changes, list of files modified, link to the Linear ticket as a clickable URL (e.g., `[TRUNK-XXXXX](https://linear.app/trunk/issue/TRUNK-XXXXX)`), and open questions if any -- The Linear ticket link in the body and the `[TRUNK-XXXXX]` prefix in the title ensure cross-referencing between GitHub and Linear - -### 4. Linear Ticket Update -- **Always include the full PR URL** (e.g., `https://github.com/trunk-io/docs/pull/123`) in any Linear comment or description. Never reference a PR without its link. -- If a Linear ticket ID was provided: - - Add a comment to the ticket with: - - The PR URL as a clickable link - - A brief summary of what the docs change covers - - List of files modified - - Any open questions - - Update the ticket status to "In Review" - - Assign the ticket to the author if unassigned -- If no ticket exists: - - Create a new Linear ticket in the Trunk Engineering team - - Assign it to the specified author (default: "me") - - Label it with `docs` - - Include the PR URL as a clickable link in the description - - Report the new ticket ID - -## Output -Report: -- Branch name -- Commit SHA -- PR URL -- Linear ticket ID (existing or newly created) -- Any issues encountered diff --git a/.claude/agents/changelog-writer.md b/.claude/agents/changelog-writer.md deleted file mode 100644 index 21fdc9f0..00000000 --- a/.claude/agents/changelog-writer.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -name: changelog-writer -description: "Writes changelog entries for shipped features. Use when given Linear tickets or feature descriptions and the task is specifically changelog/release notes. Use proactively for changelog tasks." -model: sonnet -tools: Read, Write, Bash, Grep, Glob ---- - -You write changelog entries for Trunk.io matching the style at -www.trunk.io/changelog. Entries are staged for manual upload to DatoCMS. - -## Style Guide -- Lead with the user benefit, not the implementation detail -- Use present tense ("Merge Queue now supports...") -- Include a brief "why this matters" sentence -- Keep to 2-4 sentences max -- End with a link to relevant docs if applicable -- Format: date, title, description, docs link - -## Process -1. Look up the Linear ticket(s) for context and linked PRs -2. Check existing docs in the local repo for related pages to link to -3. Draft the changelog entry -4. Flag any ambiguities as questions - -## Output -Write the changelog entry to `.claude/tmp/changelogs/changelog-.md` -using this format: - -```markdown ---- -date: YYYY-MM-DD -title: [Short, punchy title] -product: [Merge Queue | Flaky Tests | CI Autopilot | Code Quality | Platform] -status: draft -linear: [TRUNK-XXXXX URL if applicable] -docs_pr: [GitHub PR URL if applicable] ---- - -[2-4 sentence description. Lead with user benefit. Present tense.] - -[Learn more →](https://docs.trunk.io/path/to/relevant/page) -``` - -If processing multiple features, write one file per changelog entry. - -After writing, list all staged files in your response so the user knows -what's ready for DatoCMS upload. diff --git a/.claude/agents/doc-researcher.md b/.claude/agents/doc-researcher.md deleted file mode 100644 index 5389ae82..00000000 --- a/.claude/agents/doc-researcher.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -name: doc-researcher -description: "Researches Linear tickets, PRs, and existing docs to compile context for documentation work. Use PROACTIVELY before doc-writer when the scope is unclear or when multiple tickets need to be surveyed." -model: sonnet -tools: Read, Grep, Glob, Bash ---- - -You are a documentation researcher for Trunk.io. Your job is to gather -and organize all available context about a feature before docs are written. - -You are working inside the local gitbook docs repository. - -## Process -1. Look up all provided Linear ticket IDs — extract descriptions, - comments, linked PRs, related tickets -2. Look up any GitHub PR URLs using `gh pr view ` — extract - descriptions, changed files, and review comments -3. Explore the local filesystem to find any current docs coverage of the topic -4. Identify gaps between what exists and what's needed - -## Output -Produce a research brief with: -- **Feature Summary**: What is this, in plain terms -- **Linear Tickets**: ID, title, status, assignee for each, with links -- **PRs**: All linked PRs with titles, URLs, status, and key changes -- **Existing Docs**: What currently exists in the repo and where (include file paths) -- **Key Code References**: Any relevant code snippets, configs, or schemas from PRs -- **Gaps**: What's missing or outdated -- **Suggested Scope**: What the doc-writer agent should focus on - -If a notes file path was provided, also write a `.sources.md` file -alongside it (same directory, same name with `.sources.md` suffix) -containing all the above in a structured, human-readable format for -cross-referencing and accuracy checks. diff --git a/.claude/agents/doc-writer.md b/.claude/agents/doc-writer.md deleted file mode 100644 index 69f0330e..00000000 --- a/.claude/agents/doc-writer.md +++ /dev/null @@ -1,77 +0,0 @@ ---- -name: doc-writer -description: "Documentation writer for Trunk features. Use when given a feature name, Slack context, and/or Linear ticket references to produce structured documentation outputs. MUST BE USED for any documentation drafting task." -model: opus ---- - -You are a senior technical writer for Trunk.io, a developer tools company -that provides merge queues and flaky test detection. - -You are working inside the local gitbook docs repository. Use the filesystem -to understand the existing doc structure, and use Linear MCP to pull ticket -details and linked PRs. - -## Your Inputs -You will receive some combination of: -- A feature name or topic -- Slack message blobs with context about the feature -- Context links (Slack threads, Slite docs, Loom videos, Google Docs, etc.) -- Linear ticket IDs to look up for details and PRs - -## Your Process -1. **Research**: Use Linear MCP to pull the ticket(s) — read descriptions, - comments, and linked PRs. Explore the local filesystem to understand - existing doc structure and find related content. -2. **Find related tickets**: Search Linear for engineering tickets related - to the feature being documented. Collect their IDs for linking later. -3. **Draft**: Write the documentation in clear, user-focused prose. -4. **Organize**: Suggest where this doc should live in the existing - docs structure based on what you see in the repo. - -## Sources File -Before drafting, write a sources file to -`.claude/tmp/sources/sources-.md` (kebab-case feature name). -If no notes file path was given, include a `### Sources` section in -your output instead. This should list every Linear ticket, GitHub PR, -existing doc file, code snippet, and external reference you used as -input, with links and brief descriptions. **All Linear ticket references -must be clickable links.** Use `gh pr view ` to read GitHub PR -details. This lets reviewers verify accuracy. - -## Required Outputs -Produce a single markdown file with these clearly labeled sections: - -### Documentation Draft -The actual docs content, written for developers. Match the tone and -structure of existing Trunk docs (examine nearby files for reference). - -### Suggested Location -Where in the docs hierarchy this should go (e.g., -`/merge-queue/configuration/parallel-queues`) with rationale based on -the actual directory structure you can see. - -### Relevant PRs -A list of PRs extracted from Linear tickets, formatted as: -- PR title | URL | status | brief relevance note - -### Context Links -List all URLs found in the input (Slack, Slite, Loom, Google Docs, etc.). -These should be attached to the Linear ticket and referenced in the PR body. - -### Related Linear Tickets -List any related engineering tickets found during research. These should -be linked as relations on the docs ticket so engineers can see the docs -work from their feature tickets. - -### Open Questions -Numbered list of things you couldn't determine from the inputs — -questions for the team to answer to complete the doc. - -### Changelog Entry -A changelog entry matching the style at www.trunk.io/changelog. -Keep it concise, user-facing, and focused on the "what" and "why." -Format: date, title, 2-3 sentence description, link to docs. - -### Roadmap Update -A brief roadmap blurb for www.trunk.io/roadmap. Include: feature name, -status (shipped/beta/coming soon), one-line description. diff --git a/.claude/agents/notes-processor.md b/.claude/agents/notes-processor.md deleted file mode 100644 index ba7fd105..00000000 --- a/.claude/agents/notes-processor.md +++ /dev/null @@ -1,322 +0,0 @@ ---- -name: notes-processor -description: "Processes a notes/drafts file into documentation changes. Use when given a markdown file from .claude/drafts/ containing Slack conversations, engineer notes, or feature descriptions. Orchestrates the full pipeline: research, write, apply changes, branch, PR, and Linear updates." -model: opus ---- - -You are a documentation pipeline orchestrator for Trunk.io. You take raw, -unstructured input (Slack threads, engineer scribbles, feature descriptions) -and produce polished documentation changes with full project tracking. - -## Your Input -A path to a markdown notes file (typically in `.claude/drafts/`). The file -may contain any combination of: -- Slack message pastes (messy formatting is expected) -- Engineer notes and bullet points -- Linear ticket references -- Feature names or descriptions -- Links to PRs, code, or external resources - -## Your Process - -### Phase 1: Parse and Understand -1. Read the notes file completely -2. Extract: - - **Feature/change name** — what is this about? - - **Linear ticket IDs** — any TRUNK-XXXXX references - - **GitHub PR URLs** — any github.com PR links. Use `gh pr view ` to read PR descriptions, changed files, and review comments for additional context - - **Context links** — collect ALL URLs found in the notes, including: - - Slack threads (`trunk-io.slack.com`) - - Slite docs (`*.slite.com`) - - Loom videos (`loom.com`) - - Notion pages, Google Docs, Confluence, or any other internal tool - - External references (blog posts, vendor docs, specs) - These are important context breadcrumbs — they will be attached to - Linear tickets and referenced in the PR body - - **Product area** — Merge Queue, Flaky Tests, CI Autopilot, Code Quality, or Admin/Setup - - **Change type** — new feature, update, fix, deprecation, or explainer - - **Key details** — what changed, why, any configuration involved - - **Priority** — if specified, otherwise infer from context - -### Phase 2: Research -1. If Linear ticket IDs were found, look them up via Linear MCP: - - Read full descriptions, comments, attachments, and linked PRs - - Note any Slack links already attached to the ticket - - Check for related tickets linked from the ticket -2. **Search Linear for related work tickets** — this is critical for - linking docs work to the engineering work it documents: - - Search by feature name, product area keywords, and relevant terms - - Search by project if the ticket belongs to a project - - Look for engineering tickets (bugs, features, tasks) that describe - the same functionality being documented - - Collect the IDs of all related tickets found — you will link these - in Phase 5 -3. Search the local docs repo for existing coverage: - - Use Glob to find related files - - Use Grep to find references to the feature/topic - - Read existing docs to understand current state -4. Search GitBook docs MCP for published content on the topic -5. Identify gaps between what exists and what the notes describe - -### Phase 2.5: Generate Sources File -Write a sources file to `.claude/tmp/sources/sources-.md`. -Use a kebab-case feature name derived from the notes file name (e.g., -`google-cloud` from `google-cloud.md`). - -This file is a human-readable manifest of everything the agent found -and used as input. It should be easy to scan for accuracy and -cross-referencing. **All Linear ticket references must be clickable -links** using `[TRUNK-XXXXX](https://linear.app/trunk/issue/TRUNK-XXXXX)`. - -Format: - -```markdown -# Sources: [Feature Name] -Generated: [date] - -## Linear Tickets -For each ticket found: -- **[TRUNK-XXXXX](https://linear.app/trunk/issue/TRUNK-XXXXX)** — [title] - - Status: [status] | Assignee: [name] - - Summary: [1-2 sentence description from ticket] - -## GitHub PRs -For each PR found (from notes file, Linear tickets, or discovered): -- **[PR title](github-url)** — [repo] #[number] - - Status: [merged/open/closed] | Author: [name] - - Summary: [1-2 sentence description from PR body] - - Key changes: [list of notable files or areas changed] - -## Existing Docs -Files in the repo that are relevant to this change: -- `[file path]` — [brief description of what it covers and its relevance] - -## Key Code References -Any code snippets, config examples, API schemas, or technical details -extracted from PRs, tickets, or Slack context that informed the docs: -- Source: [where it came from] - ``` - [the relevant snippet] - ``` - -## Context Links -All URLs extracted from the notes file and Linear tickets (Slack, Slite, -Loom, Google Docs, external references, etc.): -- [source type]: [description](url) — [what context it provided] - -## Related Linear Tickets -Tickets discovered via search that relate to the same feature/area -(these will be linked as relations on the docs ticket): -- **[TRUNK-XXXXX](https://linear.app/trunk/issue/TRUNK-XXXXX)** — [title] - - Relationship: [documents / is documented by / related to] - - Why: [brief reason this is related] - -## External References -Any external URLs, docs, or resources referenced: -- [title](url) — [why it's relevant] -``` - -This file serves as an audit trail so reviewers can verify where -information came from and check accuracy against primary sources. - - -Based on everything gathered, write the documentation changes: -- Match the tone and structure of existing Trunk docs (read nearby files) -- For **new pages**: write the full page content -- For **updates**: show the exact edits needed (old text → new text) -- For **fixes**: identify and correct the specific issues -- For **explainers**: enhance existing docs with examples, scenarios, or - clarifications based on customer feedback. Important guidelines: - - Add examples and scenarios to the relevant existing page — don't - create new pages unless the content truly doesn't fit anywhere - - Keep "happy path" workflow guides clean and scannable. Add examples - in a dedicated section (e.g., "## Examples" or "## Common scenarios") - below the main workflow steps, not inline - - Use collapsible details blocks (`
`) for edge cases or - longer scenarios so they don't clutter the page - - Prioritize the customer's actual question/confusion — write the - example that would have answered it - - If the existing page is already long, consider adding a linked - "Examples" or "Cookbook" subpage instead of making it longer - -### Phase 4: Apply Changes -Apply the documentation changes directly to the repo files: -- Edit existing files in place using the Edit tool -- Create new files using the Write tool -- Update `summary.md` if adding new pages - -### Phase 5: Branch, PR, and Linear -After changes are applied: - -1. **Branch**: Create a branch from `main` named `sam/` - - Stash any unrelated working tree changes first - - Apply only the files relevant to this change -2. **Commit**: Stage and commit with a clear message, include - `Co-Authored-By: Claude Opus 4.6 ` -3. **Push and PR**: Push to origin and create a PR via `gh pr create` with: - - **Title format:** `[TRUNK-XXXXX] Short descriptive title` — always prefix - with the Linear ticket ID in brackets (use the docs ticket ID) - - Body must include: - - **Summary** — bullet list of changes - - **Linear tickets** — link every related ticket, not just the docs ticket - - **Context links** — list all Slack, Slite, Loom, and other links - from the notes so reviewers can trace back to original context - - **Files changed** — list of files created/modified - - **Open questions** — things the agent couldn't confirm - - **Test plan** — checklist for reviewer -4. **Linear update** — this is a multi-step process: - - **4a. Create or update the docs ticket:** - - If a ticket exists: update its description to be comprehensive. - Include: what docs were changed, why, links to the PR, all context - links found in the notes (Slack, Slite, Loom, etc.), and a summary - of what the reviewer should check. Add a comment with the PR link. - Update status to "In Review". - - If no ticket exists: create one in Trunk Engineering team with - label `docs`, assigned to "me". Write a thorough description - (not just a title) covering: what changed, why, the PR link, - all context links, and open questions. Include PR link. - - **4b. Attach context links to the ticket:** - - For every URL found in the notes file (Slack, Slite, Loom, Google - Docs, Notion, external docs, etc.), add it as a link attachment on - the Linear ticket using the `links` field in `update_issue` or - `create_issue`. Use a descriptive title prefix based on the source: - - Slack: `"Slack: [channel] — [brief topic]"` - - Slite: `"Slite: [doc title or topic]"` - - Loom: `"Loom: [video title or topic]"` - - GitHub PR: `"PR: [title]"` - - Other: `"[Source]: [brief description]"` - - **4c. Link related tickets:** - - For every related Linear ticket discovered during Phase 2 research, - add a `relatedTo` relation on the docs ticket. This creates a - bidirectional link so engineers can see the docs work from their - feature tickets. - - For tickets that were explicitly referenced in the notes file - (specified by the user), also add them as relations. - - Use `update_issue` with the `relatedTo` field to set all relations - at once. Include both the specified tickets and the discovered ones. - -5. **Return to original branch**: Switch back to the branch you started on - and restore any stashed changes - -### Phase 5.5: Stage Changelog Entry -Write a changelog entry to `.claude/tmp/changelogs/changelog-.md`. -These are staged for manual upload to DatoCMS. - -Use this format: - -```markdown ---- -date: YYYY-MM-DD -title: [Short, punchy title — lead with user benefit] -product: [Merge Queue | Flaky Tests | CI Autopilot | Code Quality | Platform] -status: draft -linear: [TRUNK-XXXXX URL if applicable] -docs_pr: [GitHub PR URL] ---- - -[2-4 sentence description. Lead with user benefit. Present tense. -Include a "why this matters" sentence.] - -[Learn more →](https://docs.trunk.io/path/to/relevant/page) -``` - -### Phase 5.6: Generate Slack Post -Write a Slack-ready internal announcement to -`.claude/tmp/slack/slack-.md`. This file is meant to be -copied and pasted into Slack to notify the team about the docs change. - -Use this format: - -```markdown -**[Feature Name] — docs update ready for review** - -[1-2 sentence summary of what changed in the docs.] - -- PR: [GitHub PR URL] -- Linear: [Linear ticket URL] -- Preview: [GitBook preview URL if available, otherwise omit] - -Open questions for the team: -- [list any items needing eng confirmation] -``` - -Keep it concise — this is a Slack message, not a document. Use bold for -the title line. Include the PR and Linear links so people can click -through directly. - -### Phase 6: Generate Review Report -After the PR is created, append an entry to the daily report file at -`.claude/tmp/report.html`. If the file doesn't exist yet, create it -with a full HTML document including basic styling. Each entry should be -a self-contained review card with everything a human reviewer needs. -The HTML format makes it easy to open in a browser for quick scanning. - -If the file already exists, append the new card inside the `
` element. - -HTML template for new files: - -```html - - - - - Docs Review Report — [date] - - - -

Docs Review Report — [date]

-
-
- - -``` - -Card format to append inside `
`: - -```html -
-

PR #[number] — [short title]

- - - - - - - - - - -
Branchsam/[branch-name]
PR[url]
LinearTRUNK-XXXXX — [status]
Sources.claude/tmp/sources/sources-[featurename].md
Draft.claude/drafts/[notes-file].md
Type[new-feature / update / fix / deprecation / explainer]
Changes[1-2 sentence summary]
Context links[Slack/Slite/Loom links as clickable anchors, or "None"]
Related tickets[Linked TRUNK-XXXXX as clickable anchors, or "None"]
-
Review focus: [what the reviewer should check]
-
Open questions:
  1. [questions]
-
-``` - -The **Review focus** field is critical. Be honest about what you're -uncertain about — flag any details you inferred rather than confirmed, -any placeholder content, and any areas where the docs could be wrong. - -## Important Rules -- **Always include PR links** in Linear comments and descriptions -- **One notes file = one PR**. If a notes file describes multiple unrelated - changes, flag this and ask the user how to split them -- **Preserve the notes file** — don't delete or modify it. It's the audit trail. -- **Ask before guessing** — if the notes are too ambiguous to determine what - docs change is needed, output your best interpretation and list specific - questions rather than making assumptions diff --git a/.claude/skills/write-docs/README.md b/.claude/skills/write-docs/README.md new file mode 100644 index 00000000..bedde142 --- /dev/null +++ b/.claude/skills/write-docs/README.md @@ -0,0 +1,180 @@ +# write-docs skill + +An end-to-end documentation pipeline that turns raw notes, Slack pastes, and PR references into reviewed docs PRs with full Linear tracking. Invoked as `/write-docs `. + +## Flow + +```mermaid +flowchart TD + A["/write-docs .claude/drafts/feature.md"] --> B{Phase 0a:\nExact Dupe Check} + B -->|PR/branch exists| STOP1["Show existing PR\nAsk: update, redo, or skip?"] + B -->|No match| B2{Phase 0b:\nOverlap Check} + B2 -->|Other PR touches\nsame files| STOP2["Show overlapping PR\nAsk: proceed, wait, or skip?"] + B2 -->|No overlap| C + + subgraph "Research & Plan" + C["Phase 1: Parse\nRead draft, extract tickets,\nPRs, context links"] --> D["Phase 2: Research\nLinear tickets, docs search,\ntrunk2 PR diffs, gap analysis"] + D --> E["Phase 2.5: Sources\nWrite audit trail to\n.claude/tmp/feature/sources.md"] + end + + E --> F + + subgraph "Write & Ship" + F["Phase 3: Draft\nEdit existing pages or\ncreate new docs files"] --> G["Phase 4: Branch & PR\nStash → branch → commit →\npush → gh pr create"] + end + + G --> H + + subgraph "Track & Notify" + H["Phase 5: Linear\nCreate/update ticket,\nattach links, add relations"] --> I["Phase 6: Stage\nWrite slack.md,\nappend to report.html"] + end + + I --> J["Phase 7: Clean Up\nRestore original branch\nand stashed changes"] + + J --> K["Output Summary\nPR link, Linear link,\nfiles changed, open questions"] + + style A fill:#4a9eff,color:#fff + style STOP fill:#ff6b6b,color:#fff + style K fill:#51cf66,color:#fff +``` + +### Input to output mapping + +```mermaid +flowchart LR + subgraph Inputs + DRAFT[".claude/drafts/\nfeature.md"] + LINEAR["Linear\ntickets"] + GITHUB["trunk2\nPRs"] + DOCS["Existing\ndocs pages"] + end + + subgraph "write-docs skill" + SKILL["Research → Draft → Ship"] + end + + subgraph "Outputs" + PR["GitHub PR\n(docs repo)"] + TICKET["Linear ticket\n(updated)"] + SOURCES[".claude/tmp/feature/\nsources.md"] + SLACK[".claude/tmp/feature/\nslack.md"] + REPORT[".claude/tmp/\nreport.html"] + end + + DRAFT --> SKILL + LINEAR --> SKILL + GITHUB --> SKILL + DOCS --> SKILL + + SKILL --> PR + SKILL --> TICKET + SKILL --> SOURCES + SKILL --> SLACK + SKILL --> REPORT + + PR -. "reviewer reads" .-> SOURCES + SLACK -. "copy-paste to\nSlack channel" .-> TEAM(("Team")) + REPORT -. "open in browser" .-> DASHBOARD(("Standups")) +``` + +## What it does + +Given a notes file (or PR numbers / Linear ticket IDs), the skill: + +1. **Checks for duplicates and overlaps** — stops if a PR/branch already exists for this draft, or if another open PR already touches the same docs files +2. **Parses** the input to extract feature details, ticket IDs, PR URLs, and context links +3. **Researches** the topic across Linear, GitHub PRs, existing docs, and the GitBook MCP +4. **Drafts** documentation changes (new pages or edits to existing files) +5. **Ships** a branch, commit, and PR with a structured body +6. **Updates Linear** — description, status, attachments, related ticket links, and a review comment +7. **Stages outputs** — Slack announcement, sources audit, and HTML report card + +## Inputs + +| Input type | Example | What happens | +| ----------------- | --------------------------------- | ----------------------------------------------------------------------------- | +| Notes file | `.claude/drafts/flag-as-flaky.md` | Primary mode. Reads the file, extracts all metadata, researches, writes docs. | +| trunk2 PR numbers | `3187 3177` | Reads PR details via `gh`, extracts Linear IDs from titles/branches. | +| Linear ticket IDs | `TRUNK-17633` | Looks up ticket, finds related PRs and context. | +| Deploy tag | `v126` | Documents features shipped in a specific release. | + +Notes files follow the template at `.claude/drafts/TEMPLATE.md`. Key sections: Type, Linear Tickets, What Changed, GitHub PRs, Context Links, Target Docs, and freeform Context at the bottom. + +## Outputs + +Everything the skill produces falls into two categories: **committed work** (the PR) and **staged artifacts** (local files for downstream use). + +### Committed: the docs PR + +- Branch: `/` (username from `git config user.name`, kebab-cased) +- PR title: `[TRUNK-XXXXX] Short descriptive title` +- PR body includes: summary, Linear links, context links, files changed, open questions, test plan +- One PR per notes file — never mixes unrelated changes + +### Staged: `.claude/tmp//` + +All staged files are gitignored. Outputs are bundled under a directory matching the draft filename (e.g., `.claude/drafts/flag-as-flaky.md` → `.claude/tmp/flag-as-flaky/`). + +#### `sources.md` + +**Purpose:** Audit trail for reviewers to verify accuracy. + +Contains every source consulted during research: Linear tickets (with URLs and status), GitHub PRs (with merge dates), existing docs files examined, context links from the notes, and related tickets discovered via search. + +**Who uses it:** The PR reviewer. Lets them trace any claim in the docs back to its source without re-doing the research. + +#### `slack.md` + +**Purpose:** Pre-written Slack message for the team channel announcing the docs update. Copy-paste directly into Slack. + +Uses Slack mrkdwn syntax (not Markdown) so formatting renders correctly when pasted: `*bold*` for bold, `` for links, `•` for bullets. No conversion needed. + +**Who uses it:** Whoever posts docs updates. Open file, select all, paste into Slack. + +### `report.html` (cumulative, at `.claude/tmp/report.html`) + +**Purpose:** Cumulative dashboard of all docs work processed through the pipeline. + +Each run appends an HTML card with: PR link, Linear link, change type badge, changes summary, context links, related tickets, review focus areas, and open questions. Styled for quick scanning in a browser. + +**Who uses it:** For tracking all in-flight docs work across multiple runs. Open in a browser to see everything at a glance. Also useful for standups and weekly reports. + +### Linear updates + +The skill also modifies state in Linear: + +- **Ticket description** — overwritten with PR link, files changed, and context +- **Status** — set to "In Review" +- **Attachments** — context links (Slack, Slite, Loom) added with descriptive titles +- **Relations** — `relatedTo` links added for every related engineering ticket found during research +- **Comment** — PR link and open questions posted as a comment + +If no docs ticket exists, one is created in the Docs Maintenance project with the `docs` label. + +## Pipeline phases + +``` +Phase 0a: Dupe check Check for existing PRs/branches from this draft +Phase 0b: Overlap check Check if other open PRs touch the same docs files +Phase 1: Parse Read notes file, extract metadata +Phase 2: Research Linear lookup, docs search, PR diffs, gap analysis +Phase 2.5: Sources Write sources audit file +Phase 3: Draft Write or edit documentation files +Phase 4: Branch/PR Stash → branch → commit → push → gh pr create +Phase 5: Linear Create/update ticket, attach links, add relations +Phase 6: Stage Write Slack post, append to report.html +Phase 7: Clean up Return to original branch, restore stash +``` + +## Batch processing + +To process multiple notes files, run `/write-docs` on each file sequentially. Each gets its own branch, PR, Linear ticket, and output directory under `.claude/tmp/`. The skill handles git stash/restore between runs to avoid conflicts. + +## Where redundancy might exist + +If you're evaluating overlap with other repos or tools: + +- **Slack posts** overlap with any existing docs announcement process — these are pre-written but not sent +- **Linear updates** overlap with manual ticket management — the skill automates what would otherwise be manual status/link/comment updates +- **Sources files** are unique to this pipeline — no other tool produces this audit trail +- **report.html** is unique to this pipeline — a local-only dashboard, not synced anywhere diff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.md new file mode 100644 index 00000000..7f0ae5f4 --- /dev/null +++ b/.claude/skills/write-docs/SKILL.md @@ -0,0 +1,209 @@ +--- +name: write-docs +description: Process notes, Slack threads, or trunk2 deploy context into documentation changes. Creates a branch, edits docs, opens a PR, and updates Linear. Use when given a notes file from .claude/drafts/, trunk2 PR numbers, Linear ticket IDs, or a deploy tag to document. +allowed-tools: Bash(git *), Bash(gh pr *), Bash(gh issue *), Bash(gh api *), Read, Write, Edit, Glob, Grep, mcp__claude_ai_Linear__get_issue, mcp__claude_ai_Linear__list_issues, mcp__claude_ai_Linear__list_projects, mcp__claude_ai_Linear__save_issue, mcp__claude_ai_Linear__save_comment, mcp__claude_ai_Linear__create_attachment, mcp__claude_ai_trunk_docs__searchDocumentation, WebFetch +--- + +Process raw input (notes files, Slack threads, engineer context, trunk2 deploy info) into polished documentation changes with full project tracking. + +## Products + +Documentation is organized by product: +- **Merge Queue** — `/merge-queue/` in the docs repo +- **Flaky Tests** — `/flaky-tests/` in the docs repo +- **CI Autopilot** — `/ci-autopilot/` in the docs repo +- **Code Quality** — `/code-quality/` in the docs repo +- **Setup & Administration** — `/setup-and-administration/` in the docs repo + +## Inputs + +The user may provide any combination of: +- **A notes file path** (e.g., `.claude/drafts/my-feature.md`) — the primary input mode. Contains Slack pastes, engineer notes, Linear ticket IDs, context links. +- **trunk2 PR numbers** — PRs from the product repo (`trunk-io/trunk2`) to document +- **Linear ticket IDs** — `TRUNK-NNNNN` references to look up +- **A deploy tag** (e.g., `v126`) — document features shipped in a specific release +- **Context links** — Slack threads, Slite docs, Loom videos, etc. +- **A specific docs page to update** — if the user knows what needs changing + +If a notes file is provided, use `.claude/drafts/TEMPLATE.md` as the reference format. + +## Steps + +### Phase 0: Duplicate and Overlap Check + +Before doing any work, check if this draft has already been processed or if another PR already covers the same docs: + +#### Step 1: Check for existing PRs/branches from this draft + +1. **Determine the expected branch name**: From the draft filename, derive the kebab-case topic (e.g., `flag-as-flaky.md` → `flag-as-flaky`). Run `git config user.name` to get the username prefix. The expected branch pattern is `/` (with possible suffix variations). + +2. **Check for existing PRs**: Run `gh pr list --repo trunk-io/docs --state open --head "" --json number,title,url,headRefName` to find any open PR from a matching branch. Also search by draft name: `gh pr list --repo trunk-io/docs --state open --json number,title,url,headRefName | jq '.[] | select(.headRefName | contains(""))'`. + +3. **Check for existing local branches**: Run `git branch --list "**"` to find local branches matching this draft. + +4. **If a match is found**: Stop and show the user: + - The existing PR number, title, and URL (if any) + - The existing branch name (if any) + - Ask: "A PR/branch already exists for this draft. Would you like to: (a) update the existing PR, (b) close it and start fresh, or (c) skip this draft?" + - Do NOT proceed until the user responds. + +#### Step 2: Check for overlapping PRs from other authors + +Even if no exact match exists, another PR may already cover the same docs pages. + +1. **Read the draft** to identify the target docs files/product area (from the `Target Docs` section or by inferring from the topic — e.g., a "flag as flaky" draft targets `flaky-tests/detection.md`). + +2. **List all open PRs**: Run `gh pr list --repo trunk-io/docs --state open --json number,title,headRefName,url --limit 50`. + +3. **Check for file overlap**: For any PR that looks potentially related (based on title or branch name matching the same product area), run `gh pr view --repo trunk-io/docs --json files --jq '[.files[].path]'` and compare against the draft's target files. + +4. **If overlapping PRs are found**: Stop and show the user: + - The overlapping PR number, title, URL, and author + - Which target files overlap + - Ask: "PR #NNN already touches [overlapping files]. Would you like to: (a) proceed anyway (changes will likely conflict), (b) wait for that PR to merge first, or (c) skip this draft?" + - Do NOT proceed until the user responds. + +5. **If no overlaps found**: Continue to Phase 1. + +### Phase 1: Parse and Understand + +1. If a notes file was provided, read it completely and extract: + - Feature/change name + - Linear ticket IDs (`TRUNK-NNNNN`) + - GitHub PR URLs or numbers + - Context links (Slack, Slite, Loom, Google Docs, etc.) + - Product area + - Change type (new feature, update, fix, deprecation, explainer) + - Key details about what changed and why + +2. If trunk2 PR numbers or a deploy tag were provided instead: + - Use `gh pr view --repo trunk-io/trunk2` to get PR details + - Extract Linear ticket IDs from PR titles and branch names + +### Phase 2: Research + +3. **Look up Linear tickets**: Use `mcp__claude_ai_Linear__get_issue` for each ticket ID to get descriptions, status, assignee, linked PRs, and related tickets. + +4. **Search Linear for related work**: Search by feature name and product area to find engineering tickets that describe the same functionality. Collect related ticket IDs for linking later. + +5. **Search existing docs**: Use `mcp__claude_ai_trunk_docs__searchDocumentation` to find published docs on the topic. Also search the local filesystem: + - Use Glob to find related files by path + - Use Grep to find references to the feature/topic + - Read `summary.md` to understand the docs hierarchy + +6. **Read trunk2 PR diffs** (if PR numbers available): Use `gh pr diff --repo trunk-io/trunk2 --name-only` to understand what code changed, then read key files for context. + +7. **Identify gaps**: Compare what exists in the docs vs. what the notes/PRs describe. Determine: + - Does a page need updating, or does a new page need creating? + - What sections are affected? + - What's accurate vs. outdated? + +### Phase 2.5: Generate Sources File + +8. Determine the output directory from the draft filename (e.g., `.claude/drafts/flag-as-flaky.md` → `.claude/tmp/flag-as-flaky/`). All staged outputs for this run go under this directory. + + Write a sources audit trail to `.claude/tmp//sources.md`. This lets reviewers verify accuracy. Include: + - All Linear tickets found (with clickable links) + - All GitHub PRs (with links, status, key changes) + - Existing docs files relevant to this change + - Key code references from PRs + - All context links from the notes + - Related Linear tickets discovered via search + +### Phase 3: Draft Documentation + +9. Write or edit documentation: + - **Match the tone and structure of existing Trunk docs** — read nearby files for reference + - For **new pages**: write the full page content + - For **updates**: edit the existing file(s) in place + - For **explainers**: add examples and scenarios to the relevant existing page. Use collapsible `
` blocks for edge cases. Keep happy-path guides clean. + - Update `summary.md` if adding new pages + + Writing guidelines: + - Lead with the user benefit, not implementation details + - Use present tense ("Merge Queue now supports...") + - Include practical examples and code snippets where relevant + - Don't mention internal systems (ClickHouse, Prisma, SST, Lambda) + - Use the customer's vocabulary, not engineering jargon + +### Phase 4: Create Branch, Commit, and PR + +10. **Branch**: Create a branch from `main`. Determine the git username by running `git config user.name` and converting it to kebab-case (e.g., "Sam Gutentag" → `sam-gutentag`). Name the branch `/`. + - Stash any unrelated working tree changes first + - Apply only the files relevant to this change + +11. **Commit**: Stage the changed files and commit with a clear message. Include `Co-Authored-By: Claude Opus 4.6 ` + +12. **Push and PR**: Push to origin and create a PR via `gh pr create` with: + - **Title format:** `[TRUNK-XXXXX] Short descriptive title` (prefix with Linear ticket ID if one exists) + - Body containing: + - **Summary** — bullet list of changes + - **Linear tickets** — clickable links to all related tickets + - **Context links** — all Slack, Slite, Loom links from the notes + - **Files changed** — list of files created/modified + - **Open questions** — things that couldn't be confirmed from available context + - **Test plan** — checklist for reviewer (e.g., "check GitBook preview", "verify code example works") + +### Phase 5: Update Linear + +13. **Create or update the docs ticket**: + - If a ticket exists: update description with PR link, context links, summary of changes. Add a comment with the PR link. Update status to "In Review". + - If no ticket exists: create one in Trunk Engineering team with `docs` label, assigned to "me". Include PR link and full context. + +14. **Attach context links**: For every URL from the notes (Slack, Slite, Loom, etc.), add it as an attachment on the Linear ticket with a descriptive title (e.g., `"Slack: #channel — topic"`). + +15. **Link related tickets**: For every related engineering ticket discovered during research, add a `relatedTo` relation on the docs ticket. + +### Phase 6: Stage Outputs + +16. **Slack post**: Write to `.claude/tmp//slack.md`. This file must be directly copy-pasteable into Slack with correct formatting. Use Slack's mrkdwn syntax (not Markdown): + - Bold: `*text*` (single asterisks, not double) + - Links: `` + - Bullets: `•` (bullet character, not `-`) + - No Markdown-style headers (`##`), links (`[text](url)`), or bold (`**text**`) + + Format: + ``` + *[Feature Name] — docs update ready for review* + + [1-2 sentence summary of what changed in the docs.] + + • PR: + • Linear: + + *Open questions for the team:* + • [list any items needing eng confirmation] + ``` + +17. **Review report**: Append an HTML card to `.claude/tmp/report.html` with PR link, Linear link, changes summary, review focus areas, and open questions. If the file doesn't exist, create it with basic HTML styling. + +### Phase 7: Clean Up + +19. Return to the original branch and restore any stashed changes. + +20. **Output summary**: Show the user: + - Branch name and PR link + - Linear ticket link + - Files changed (list) + - Open questions (numbered) + - Staged output files (slack, sources) + +## Guidelines + +- **One notes file = one PR.** If a notes file describes multiple unrelated changes, flag this and ask how to split. +- **Preserve the notes file** — don't delete or modify it. It's the audit trail. +- **Ask before guessing** — if the notes are too ambiguous, output your best interpretation and list specific questions rather than making assumptions. +- **Always include PR links** in Linear comments and descriptions. +- **Match existing style** — read adjacent doc files before writing. Don't introduce new formatting conventions. +- **Keep happy paths clean** — add examples in dedicated sections, not inline with workflow steps. +- **Prioritize accuracy** — flag anything you inferred vs. confirmed in the open questions. + +## Batch Processing + +To process multiple notes files: +``` +Process each notes file in .claude/drafts/ one at a time. +For each: research, draft, apply, branch/PR, update Linear, then move to the next. +``` + +Each file gets its own branch (`/`), PR, Linear ticket, and output directory under `.claude/tmp/`. Process one at a time to avoid git conflicts. From 07ad22bba6a3a02d27ba83bf1fb3458c7b699461 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Thu, 12 Mar 2026 16:32:29 -0700 Subject: [PATCH 14/15] Restructure write-docs skill with progressive disclosure and add Slack/Slite MCP Apply best practices from Claude skill authoring guide: - Split SKILL.md into main file + OVERLAP-CHECK.md and OUTPUTS.md reference files for progressive disclosure (Claude loads them only when reaching the relevant phase) - Trim SKILL.md from 210 to ~130 lines by removing what Claude already knows - Add progress checklist for tracking workflow phases - Add table of contents for navigability - Expand Phase 2 research to include Slite (PRDs, specs) and Slack (#team-flaky-tests, #team-merge-queue) as additional context sources - Merge DEMO.md into skill README.md as the single human-facing reference - Rename "agents" to "skills" in drafts template Co-Authored-By: Claude Opus 4.6 --- .claude/drafts/TEMPLATE.md | 6 +- .claude/skills/write-docs/OUTPUTS.md | 58 ++++ .claude/skills/write-docs/OVERLAP-CHECK.md | 51 +++ .claude/skills/write-docs/README.md | 342 +++++++++++++-------- .claude/skills/write-docs/SKILL.md | 239 +++++--------- 5 files changed, 410 insertions(+), 286 deletions(-) create mode 100644 .claude/skills/write-docs/OUTPUTS.md create mode 100644 .claude/skills/write-docs/OVERLAP-CHECK.md diff --git a/.claude/drafts/TEMPLATE.md b/.claude/drafts/TEMPLATE.md index 64c473a1..57852d0d 100644 --- a/.claude/drafts/TEMPLATE.md +++ b/.claude/drafts/TEMPLATE.md @@ -18,12 +18,12 @@ + and the skills will figure it out. --> ## GitHub PRs + The skills will read PR descriptions and diffs for additional context. --> ## Context Links @@ -34,7 +34,7 @@ ## Target Docs + Otherwise the skills will determine this from the repo structure. --> ## Context diff --git a/.claude/skills/write-docs/OUTPUTS.md b/.claude/skills/write-docs/OUTPUTS.md new file mode 100644 index 00000000..b6e24267 --- /dev/null +++ b/.claude/skills/write-docs/OUTPUTS.md @@ -0,0 +1,58 @@ +# Output Formats + +Reference for all outputs produced by the write-docs skill. + +## Contents + +- [PR body format](#pr-body-format) +- [Slack post format](#slack-post-format) +- [Report card format](#report-card-format) + +## PR Body Format + +PR title: `[TRUNK-XXXXX] Short descriptive title` (prefix with Linear ticket ID if one exists). + +PR body sections: +- **Summary** — bullet list of changes +- **Linear tickets** — clickable links to all related tickets +- **Context links** — all Slack, Slite, Loom links from the notes +- **Files changed** — list of files created/modified +- **Open questions** — things that could not be confirmed from available context +- **Test plan** — checklist for reviewer (e.g., "check GitBook preview", "verify code example works") + +## Slack Post Format + +Write to `.claude/tmp//slack.md`. Must be directly copy-pasteable into Slack. + +**MUST use Slack mrkdwn syntax, NOT Markdown:** +- Bold: `*text*` (single asterisks, not double) +- Links: `` +- Bullets: use the `*` character on a new line (Slack list style) +- No Markdown headers (`##`), links (`[text](url)`), or bold (`**text**`) + +Template: +``` +*[Feature Name] — docs update ready for review* + +[1-2 sentence summary of what changed in the docs.] + +* PR: +* Linear: + +*Open questions for the team:* +* [list any items needing eng confirmation] +``` + +## Report Card Format + +Append an HTML card to `.claude/tmp/report.html`. If the file does not exist, create it with basic HTML styling. + +Each card includes: +- PR link +- Linear link +- Change type badge +- Changes summary +- Context links +- Related tickets +- Review focus areas +- Open questions diff --git a/.claude/skills/write-docs/OVERLAP-CHECK.md b/.claude/skills/write-docs/OVERLAP-CHECK.md new file mode 100644 index 00000000..d361c17a --- /dev/null +++ b/.claude/skills/write-docs/OVERLAP-CHECK.md @@ -0,0 +1,51 @@ +# Duplicate & Overlap Check + +Run these checks before starting any work. Stop and ask the user if any match is found. + +## Step 1: Check for existing PRs/branches from this draft + +1. Derive the expected branch topic from the draft filename (e.g., `flag-as-flaky.md` -> `flag-as-flaky`). Get the username prefix from `git config user.name` (kebab-cased). + +2. Search for open PRs matching the branch: + ```bash + gh pr list --repo trunk-io/docs --state open --head "/" --json number,title,url,headRefName + ``` + Also search by topic keyword: + ```bash + gh pr list --repo trunk-io/docs --state open --json number,title,url,headRefName | jq '.[] | select(.headRefName | contains(""))' + ``` + +3. Check local branches: + ```bash + git branch --list "**" + ``` + +4. **If a match is found**: Show the user the existing PR/branch and ask: + - (a) Update the existing PR + - (b) Close it and start fresh + - (c) Skip this draft + + Do NOT proceed until the user responds. + +## Step 2: Check for overlapping PRs from other authors + +1. Read the draft to identify target docs files/product area. + +2. List all open PRs: + ```bash + gh pr list --repo trunk-io/docs --state open --json number,title,headRefName,url --limit 50 + ``` + +3. For any PR that looks related (by title or branch name matching the same product area), check file overlap: + ```bash + gh pr view --repo trunk-io/docs --json files --jq '[.files[].path]' + ``` + +4. **If overlapping PRs are found**: Show the user the overlapping PR and affected files, then ask: + - (a) Proceed anyway (changes will likely conflict) + - (b) Wait for that PR to merge first + - (c) Skip this draft + + Do NOT proceed until the user responds. + +5. **If no overlaps found**: Continue to Phase 1. diff --git a/.claude/skills/write-docs/README.md b/.claude/skills/write-docs/README.md index bedde142..4dfdb2d6 100644 --- a/.claude/skills/write-docs/README.md +++ b/.claude/skills/write-docs/README.md @@ -1,180 +1,278 @@ # write-docs skill -An end-to-end documentation pipeline that turns raw notes, Slack pastes, and PR references into reviewed docs PRs with full Linear tracking. Invoked as `/write-docs `. +End-to-end documentation pipeline: raw notes -> reviewed docs PR with Linear tracking. -## Flow +Invoked as `/write-docs `. -```mermaid -flowchart TD - A["/write-docs .claude/drafts/feature.md"] --> B{Phase 0a:\nExact Dupe Check} - B -->|PR/branch exists| STOP1["Show existing PR\nAsk: update, redo, or skip?"] - B -->|No match| B2{Phase 0b:\nOverlap Check} - B2 -->|Other PR touches\nsame files| STOP2["Show overlapping PR\nAsk: proceed, wait, or skip?"] - B2 -->|No overlap| C +## Directory Structure - subgraph "Research & Plan" - C["Phase 1: Parse\nRead draft, extract tickets,\nPRs, context links"] --> D["Phase 2: Research\nLinear tickets, docs search,\ntrunk2 PR diffs, gap analysis"] - D --> E["Phase 2.5: Sources\nWrite audit trail to\n.claude/tmp/feature/sources.md"] - end +``` +write-docs/ +├── SKILL.md # Main instructions (~130 lines, loaded when skill triggers) +├── OVERLAP-CHECK.md # Detailed dupe/overlap check procedure (loaded in Phase 0) +├── OUTPUTS.md # PR body, Slack post, report format specs (loaded in Phases 4-6) +└── README.md # This file (human reference only) +``` + +## How It Works + +The skill uses progressive disclosure: Claude loads SKILL.md when triggered, then reads OVERLAP-CHECK.md and OUTPUTS.md only when it reaches the relevant phase. This keeps the context window lean. + +### Pipeline + +``` +Phase 0 Duplicate & overlap check Stops if a PR/branch already covers this draft +Phase 1 Parse input Read notes file, extract tickets, PRs, context links +Phase 2 Research Linear tickets, Slite PRDs, Slack channels, + published docs, trunk2 PR diffs, gap analysis +Phase 2.5 Sources Write audit trail to .claude/tmp//sources.md +Phase 3 Draft Edit existing pages or create new docs files +Phase 4 Branch & PR Stash → branch → commit → push → gh pr create +Phase 5 Linear Create/update ticket, attach links, add relations +Phase 6 Stage Write slack.md, append to report.html +Phase 7 Clean up Restore original branch and stashed changes +``` + +### Research Sources (Phase 2) + +The skill cross-references five sources to build context before writing anything: + +| Source | What it finds | MCP Server | +| ------------------ | ---------------------------------------------------------------------------------------- | --------------------- | +| **Linear** | Ticket descriptions, status, assignees, related tickets | `claude.ai Linear` | +| **Slite** | PRDs, specs, roadmap items, knowledge base articles | `claude.ai Trunk Slite` | +| **Slack** | Team discussions, changelogs, feature context from `#team-flaky-tests`, `#team-merge-queue` | `claude.ai Slack` | +| **Published docs** | Existing documentation pages, hierarchy from `summary.md` | `claude.ai trunk docs` | +| **GitHub** | trunk2 PR diffs, code changes, implementation details | `gh` CLI | + +### Inputs + +| Input type | Example | What happens | +| ----------------- | --------------------------------- | --------------------------------------------------------------- | +| Notes file | `.claude/drafts/flag-as-flaky.md` | Primary mode. Reads file, extracts metadata, researches, writes | +| trunk2 PR numbers | `3187 3177` | Reads PR details via `gh`, extracts Linear IDs | +| Linear ticket IDs | `TRUNK-17633` | Looks up ticket, finds related PRs and context | +| Deploy tag | `v126` | Documents features shipped in a specific release | + +Notes files follow the template at `.claude/drafts/TEMPLATE.md`. + +### Outputs + +**Committed (the PR):** + +- Branch: `/` +- PR title: `[TRUNK-XXXXX] Short descriptive title` +- PR body: summary, Linear links, context links, files changed, open questions, test plan + +**Staged (gitignored, under `.claude/tmp//`):** + +- `sources.md` — audit trail for reviewers (every source consulted) +- `slack.md` — copy-pasteable Slack announcement (uses Slack mrkdwn, not Markdown) + +**Cumulative (`.claude/tmp/report.html`):** + +- HTML card appended per run — PR link, Linear link, changes summary, open questions + +**Linear:** + +- Ticket created/updated in Docs Maintenance project with `docs` label +- Context links attached (Slack, Slite, Loom, etc.) +- Related engineering tickets linked via `relatedTo` +- Status set to "In Review" + +### Prerequisites + +The skill requires these MCP servers to be connected. Verify with `claude mcp list`: - E --> F +- `claude.ai Slack` — for searching team channels +- `claude.ai Trunk Slite` — for PRDs and specs +- `claude.ai trunk docs` — for searching published docs +- `claude.ai Linear` — for ticket management +- GitHub via `gh` CLI (authenticated with access to `trunk-io/trunk2`) - subgraph "Write & Ship" - F["Phase 3: Draft\nEdit existing pages or\ncreate new docs files"] --> G["Phase 4: Branch & PR\nStash → branch → commit →\npush → gh pr create"] - end +--- - G --> H +## Demo Script - subgraph "Track & Notify" - H["Phase 5: Linear\nCreate/update ticket,\nattach links, add relations"] --> I["Phase 6: Stage\nWrite slack.md,\nappend to report.html"] - end +Walkthrough for demoing `/write-docs` at an all-hands or team meeting. Total runtime: ~5 minutes. - I --> J["Phase 7: Clean Up\nRestore original branch\nand stashed changes"] +### Pre-Demo Setup (10 min before) - J --> K["Output Summary\nPR link, Linear link,\nfiles changed, open questions"] +#### 1. Clean terminal state - style A fill:#4a9eff,color:#fff - style STOP fill:#ff6b6b,color:#fff - style K fill:#51cf66,color:#fff +```bash +cd ~/TRUNK/docs +git checkout main +git pull origin main +git status # should be clean ``` -### Input to output mapping +#### 2. Verify no leftover demo artifacts -```mermaid -flowchart LR - subgraph Inputs - DRAFT[".claude/drafts/\nfeature.md"] - LINEAR["Linear\ntickets"] - GITHUB["trunk2\nPRs"] - DOCS["Existing\ndocs pages"] - end +```bash +git branch --list "*indefinite-monitor-muting*" +gh pr list --repo trunk-io/docs --state open --json number,title,headRefName | jq '.[] | select(.headRefName | contains("indefinite-monitor-muting"))' - subgraph "write-docs skill" - SKILL["Research → Draft → Ship"] - end +# If either returns results, clean up: +# gh pr close --repo trunk-io/docs --delete-branch +# git branch -D sam-gutentag/indefinite-monitor-muting +``` - subgraph "Outputs" - PR["GitHub PR\n(docs repo)"] - TICKET["Linear ticket\n(updated)"] - SOURCES[".claude/tmp/feature/\nsources.md"] - SLACK[".claude/tmp/feature/\nslack.md"] - REPORT[".claude/tmp/\nreport.html"] - end +#### 3. Verify draft and clear previous outputs - DRAFT --> SKILL - LINEAR --> SKILL - GITHUB --> SKILL - DOCS --> SKILL +```bash +cat .claude/drafts/indefinite-monitor-muting.md +rm -rf .claude/tmp/indefinite-monitor-muting/ +``` - SKILL --> PR - SKILL --> TICKET - SKILL --> SOURCES - SKILL --> SLACK - SKILL --> REPORT +#### 4. Verify MCP servers - PR -. "reviewer reads" .-> SOURCES - SLACK -. "copy-paste to\nSlack channel" .-> TEAM(("Team")) - REPORT -. "open in browser" .-> DASHBOARD(("Standups")) +```bash +claude mcp list ``` -## What it does +All five should show connected (see [Prerequisites](#prerequisites) above). -Given a notes file (or PR numbers / Linear ticket IDs), the skill: +#### 5. Start Claude Code -1. **Checks for duplicates and overlaps** — stops if a PR/branch already exists for this draft, or if another open PR already touches the same docs files -2. **Parses** the input to extract feature details, ticket IDs, PR URLs, and context links -3. **Researches** the topic across Linear, GitHub PRs, existing docs, and the GitBook MCP -4. **Drafts** documentation changes (new pages or edits to existing files) -5. **Ships** a branch, commit, and PR with a structured body -6. **Updates Linear** — description, status, attachments, related ticket links, and a review comment -7. **Stages outputs** — Slack announcement, sources audit, and HTML report card +```bash +claude +``` -## Inputs +Wait for it to load. Verify `/write-docs` is recognized. -| Input type | Example | What happens | -| ----------------- | --------------------------------- | ----------------------------------------------------------------------------- | -| Notes file | `.claude/drafts/flag-as-flaky.md` | Primary mode. Reads the file, extracts all metadata, researches, writes docs. | -| trunk2 PR numbers | `3187 3177` | Reads PR details via `gh`, extracts Linear IDs from titles/branches. | -| Linear ticket IDs | `TRUNK-17633` | Looks up ticket, finds related PRs and context. | -| Deploy tag | `v126` | Documents features shipped in a specific release. | +#### 6. Terminal setup -Notes files follow the template at `.claude/drafts/TEMPLATE.md`. Key sections: Type, Linear Tickets, What Changed, GitHub PRs, Context Links, Target Docs, and freeform Context at the bottom. +- Font size: 18-20pt for readability +- Terminal width: full screen, max 120 chars +- Dark theme for projector visibility -## Outputs +### The Demo -Everything the skill produces falls into two categories: **committed work** (the PR) and **staged artifacts** (local files for downstream use). +#### ACT 1: The Problem (30 seconds) -### Committed: the docs PR +**[Speaking to audience, terminal visible but idle]** -- Branch: `/` (username from `git config user.name`, kebab-cased) -- PR title: `[TRUNK-XXXXX] Short descriptive title` -- PR body includes: summary, Linear links, context links, files changed, open questions, test plan -- One PR per notes file — never mixes unrelated changes +> "Quick show of hands — who's had to write documentation for a feature someone else built? Yeah. It's not the writing that's painful, it's the context-gathering. You're reading Slack threads, digging through PRs, searching Linear, figuring out which docs pages need updating. Then you do the actual writing. Then you create a branch, open a PR, update the ticket, post in Slack. That's 30 minutes for something that should take 5." -### Staged: `.claude/tmp//` +> "We built a Claude Code skill that does all of that from a single command. Let me show you." -All staged files are gitignored. Outputs are bundled under a directory matching the draft filename (e.g., `.claude/drafts/flag-as-flaky.md` → `.claude/tmp/flag-as-flaky/`). +#### ACT 2: Show the Input (30 seconds) -#### `sources.md` +**[In Claude Code, type:]** + +``` +cat .claude/drafts/indefinite-monitor-muting.md +``` -**Purpose:** Audit trail for reviewers to verify accuracy. +**[Let the file scroll. Point out key sections:]** + +> "This is a notes file — it's what an engineer or PM drops into our drafts folder. It has the feature name, links to the PRs that shipped it, and which docs pages need updating. It's rough and that's fine — it's input, not output." + +> "Notice there's no Linear ticket yet, no branch, no PR. Just notes." + +#### ACT 3: Run the Skill (2-3 minutes) + +**[Type the command:]** + +``` +/write-docs .claude/drafts/indefinite-monitor-muting.md +``` -Contains every source consulted during research: Linear tickets (with URLs and status), GitHub PRs (with merge dates), existing docs files examined, context links from the notes, and related tickets discovered via search. +**[Narrate each phase as it runs. Don't rush — let the audience watch the tool calls.]** -**Who uses it:** The PR reviewer. Lets them trace any claim in the docs back to its source without re-doing the research. +When you see `gh pr list` calls: +> "Phase zero — it's checking whether someone already opened a PR for this, or if another PR touches the same docs files." -#### `slack.md` +When you see `mcp__claude_ai_Linear` calls: +> "Now it's researching. Starts with Linear to get ticket context..." -**Purpose:** Pre-written Slack message for the team channel announcing the docs update. Copy-paste directly into Slack. +When you see Slite or Slack MCP calls: +> "It's searching our Slite knowledge base for PRDs and checking the #team-flaky-tests Slack channel for recent discussion. This is context that used to take 10 minutes of manual digging." -Uses Slack mrkdwn syntax (not Markdown) so formatting renders correctly when pasted: `*bold*` for bold, `` for links, `•` for bullets. No conversion needed. +When you see `gh pr view` or `gh pr diff` calls: +> "Reading the trunk2 PR to see what code actually shipped." -**Who uses it:** Whoever posts docs updates. Open file, select all, paste into Slack. +When you see a file being written to `.claude/tmp/`: +> "That's the sources file — an audit trail so reviewers can trace any claim back to its source." -### `report.html` (cumulative, at `.claude/tmp/report.html`) +When you see `Edit` tool calls on docs files: +> "Now it's writing the actual docs. It read the existing pages first to match our tone and structure." -**Purpose:** Cumulative dashboard of all docs work processed through the pipeline. +When you see `git` commands: +> "Creating a branch, committing, pushing..." -Each run appends an HTML card with: PR link, Linear link, change type badge, changes summary, context links, related tickets, review focus areas, and open questions. Styled for quick scanning in a browser. +When you see `gh pr create`: +> "And there's the PR." -**Who uses it:** For tracking all in-flight docs work across multiple runs. Open in a browser to see everything at a glance. Also useful for standups and weekly reports. +When you see Linear calls: +> "Creating a Linear ticket, attaching the PR link, context URLs, and linking related engineering tickets." -### Linear updates +#### ACT 4: Show the Outputs (1 minute) -The skill also modifies state in Linear: +**[Claude will output a summary with links. Click through each one:]** -- **Ticket description** — overwritten with PR link, files changed, and context -- **Status** — set to "In Review" -- **Attachments** — context links (Slack, Slite, Loom) added with descriptive titles -- **Relations** — `relatedTo` links added for every related engineering ticket found during research -- **Comment** — PR link and open questions posted as a comment +**GitHub PR** — open in browser: +> "The title has the Linear ticket ID. The body has open questions — things it couldn't confirm from the available context. It flags what needs human verification instead of guessing." -If no docs ticket exists, one is created in the Docs Maintenance project with the `docs` label. +**Linear ticket** — open in browser: +> "Docs Maintenance project, assigned to me, status In Review. It attached the PR link, the Slack threads it found, and any Slite docs it consulted." -## Pipeline phases +**[Show staged outputs:]** ``` -Phase 0a: Dupe check Check for existing PRs/branches from this draft -Phase 0b: Overlap check Check if other open PRs touch the same docs files -Phase 1: Parse Read notes file, extract metadata -Phase 2: Research Linear lookup, docs search, PR diffs, gap analysis -Phase 2.5: Sources Write sources audit file -Phase 3: Draft Write or edit documentation files -Phase 4: Branch/PR Stash → branch → commit → push → gh pr create -Phase 5: Linear Create/update ticket, attach links, add relations -Phase 6: Stage Write Slack post, append to report.html -Phase 7: Clean up Return to original branch, restore stash +cat .claude/tmp/indefinite-monitor-muting/slack.md +cat .claude/tmp/indefinite-monitor-muting/sources.md ``` -## Batch processing +> "A copy-pasteable Slack post and a full sources audit trail." + +#### ACT 5: Wrap Up (30 seconds) + +> "From one command and a rough notes file: a docs PR, a Linear ticket, an audit trail, and a team notification. About 3 minutes." + +> "The skill searches five systems — Linear, Slite, Slack, our published docs, and GitHub PRs — to build context before writing a single line. Every PR still gets human review." + +### Q&A + +**"What if the docs it writes are wrong?"** +> "Every PR gets human review. The skill flags open questions explicitly. It's doing the 80%, a human does the last 20%." + +**"Can this work for other repos?"** +> "The skill is specific to our docs workflow, but the pattern is portable. You write a SKILL.md describing the pipeline and Claude Code follows it." -To process multiple notes files, run `/write-docs` on each file sequentially. Each gets its own branch, PR, Linear ticket, and output directory under `.claude/tmp/`. The skill handles git stash/restore between runs to avoid conflicts. +**"How long did it take to build?"** +> "About 130 lines of instructions plus two reference files. The iteration was the slow part — maybe 2-3 sessions." + +**"What if it creates a PR that conflicts with someone else's work?"** +> "Phase 0 catches that. It checks every open PR for file-level overlap before doing any work." + +**"Does it handle new pages or just updates?"** +> "Both. New pages get created and added to summary.md. Updates edit existing files in place." + +**"How does it know what's in Slite and Slack?"** +> "We connected them as MCP servers — same protocol as Linear. The skill searches them during research, and knows to check #team-flaky-tests and #team-merge-queue for product context." + +### Post-Demo Cleanup + +```bash +gh pr close --repo trunk-io/docs --delete-branch +git checkout main +git branch -D sam-gutentag/indefinite-monitor-muting 2>/dev/null +rm -rf .claude/tmp/indefinite-monitor-muting/ +``` -## Where redundancy might exist +### Dry Run Checklist -If you're evaluating overlap with other repos or tools: +Do a full dry run the day before. Clean up everything so the live demo starts fresh. -- **Slack posts** overlap with any existing docs announcement process — these are pre-written but not sent -- **Linear updates** overlap with manual ticket management — the skill automates what would otherwise be manual status/link/comment updates -- **Sources files** are unique to this pipeline — no other tool produces this audit trail -- **report.html** is unique to this pipeline — a local-only dashboard, not synced anywhere +- [ ] Draft file exists at `.claude/drafts/indefinite-monitor-muting.md` +- [ ] No existing branch `sam-gutentag/indefinite-monitor-muting` +- [ ] No existing PR for indefinite-monitor-muting +- [ ] No existing `.claude/tmp/indefinite-monitor-muting/` directory +- [ ] Claude Code starts cleanly and recognizes the skill +- [ ] MCP servers are responding (Linear, GitBook, Slack, Slite) +- [ ] Terminal font size is readable from the back of the room +- [ ] You've timed the run — should be 2-4 minutes +- [ ] You know where to find the PR and Linear links in the output +- [ ] Linear "Docs Maintenance" project view is open in a browser tab diff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.md index 7f0ae5f4..56cdc7bb 100644 --- a/.claude/skills/write-docs/SKILL.md +++ b/.claude/skills/write-docs/SKILL.md @@ -1,209 +1,126 @@ --- name: write-docs -description: Process notes, Slack threads, or trunk2 deploy context into documentation changes. Creates a branch, edits docs, opens a PR, and updates Linear. Use when given a notes file from .claude/drafts/, trunk2 PR numbers, Linear ticket IDs, or a deploy tag to document. -allowed-tools: Bash(git *), Bash(gh pr *), Bash(gh issue *), Bash(gh api *), Read, Write, Edit, Glob, Grep, mcp__claude_ai_Linear__get_issue, mcp__claude_ai_Linear__list_issues, mcp__claude_ai_Linear__list_projects, mcp__claude_ai_Linear__save_issue, mcp__claude_ai_Linear__save_comment, mcp__claude_ai_Linear__create_attachment, mcp__claude_ai_trunk_docs__searchDocumentation, WebFetch +description: Process notes, Slack threads, Slite docs, or trunk2 deploy context into documentation changes. Creates a branch, edits docs, opens a PR, and updates Linear. Use when given a notes file from .claude/drafts/, trunk2 PR numbers, Linear ticket IDs, a deploy tag, Slite doc links, or when the user says "write docs", "document this", or "process drafts". +allowed-tools: Bash(git *), Bash(gh pr *), Bash(gh issue *), Bash(gh api *), Read, Write, Edit, Glob, Grep, mcp__claude_ai_Linear__get_issue, mcp__claude_ai_Linear__list_issues, mcp__claude_ai_Linear__list_projects, mcp__claude_ai_Linear__save_issue, mcp__claude_ai_Linear__save_comment, mcp__claude_ai_Linear__create_attachment, mcp__claude_ai_trunk_docs__searchDocumentation, mcp__claude_ai_Trunk_Slite__*, mcp__claude_ai_Slack__*, WebFetch --- -Process raw input (notes files, Slack threads, engineer context, trunk2 deploy info) into polished documentation changes with full project tracking. +# Writing Docs -## Products - -Documentation is organized by product: -- **Merge Queue** — `/merge-queue/` in the docs repo -- **Flaky Tests** — `/flaky-tests/` in the docs repo -- **CI Autopilot** — `/ci-autopilot/` in the docs repo -- **Code Quality** — `/code-quality/` in the docs repo -- **Setup & Administration** — `/setup-and-administration/` in the docs repo - -## Inputs - -The user may provide any combination of: -- **A notes file path** (e.g., `.claude/drafts/my-feature.md`) — the primary input mode. Contains Slack pastes, engineer notes, Linear ticket IDs, context links. -- **trunk2 PR numbers** — PRs from the product repo (`trunk-io/trunk2`) to document -- **Linear ticket IDs** — `TRUNK-NNNNN` references to look up -- **A deploy tag** (e.g., `v126`) — document features shipped in a specific release -- **Context links** — Slack threads, Slite docs, Loom videos, etc. -- **A specific docs page to update** — if the user knows what needs changing - -If a notes file is provided, use `.claude/drafts/TEMPLATE.md` as the reference format. - -## Steps - -### Phase 0: Duplicate and Overlap Check - -Before doing any work, check if this draft has already been processed or if another PR already covers the same docs: +Turn raw notes, Slack pastes, and PR references into reviewed docs PRs with full Linear tracking. -#### Step 1: Check for existing PRs/branches from this draft +## Contents -1. **Determine the expected branch name**: From the draft filename, derive the kebab-case topic (e.g., `flag-as-flaky.md` → `flag-as-flaky`). Run `git config user.name` to get the username prefix. The expected branch pattern is `/` (with possible suffix variations). +- [Inputs](#inputs) +- [Products](#products) +- [Workflow](#workflow) +- [Guidelines](#guidelines) +- [Batch processing](#batch-processing) -2. **Check for existing PRs**: Run `gh pr list --repo trunk-io/docs --state open --head "" --json number,title,url,headRefName` to find any open PR from a matching branch. Also search by draft name: `gh pr list --repo trunk-io/docs --state open --json number,title,url,headRefName | jq '.[] | select(.headRefName | contains(""))'`. +## Inputs -3. **Check for existing local branches**: Run `git branch --list "**"` to find local branches matching this draft. +The user provides any combination of: +- **Notes file** (e.g., `.claude/drafts/my-feature.md`) — primary input. Template: `.claude/drafts/TEMPLATE.md` +- **trunk2 PR numbers** — PRs from `trunk-io/trunk2` +- **Linear ticket IDs** — `TRUNK-NNNNN` references +- **Deploy tag** (e.g., `v126`) — features shipped in a release +- **Slite doc links** — PRDs, specs, or knowledge base articles from Slite +- **Context links** — Slack threads, Loom videos, Google Docs, etc. +- **Specific docs page** — if the user knows what needs changing -4. **If a match is found**: Stop and show the user: - - The existing PR number, title, and URL (if any) - - The existing branch name (if any) - - Ask: "A PR/branch already exists for this draft. Would you like to: (a) update the existing PR, (b) close it and start fresh, or (c) skip this draft?" - - Do NOT proceed until the user responds. +## Products -#### Step 2: Check for overlapping PRs from other authors +Docs are organized by product area: +- **Merge Queue** — `/merge-queue/` +- **Flaky Tests** — `/flaky-tests/` +- **CI Autopilot** — `/ci-autopilot/` +- **Code Quality** — `/code-quality/` +- **Setup & Administration** — `/setup-and-administration/` -Even if no exact match exists, another PR may already cover the same docs pages. +## Workflow -1. **Read the draft** to identify the target docs files/product area (from the `Target Docs` section or by inferring from the topic — e.g., a "flag as flaky" draft targets `flaky-tests/detection.md`). +Copy this checklist and track progress: -2. **List all open PRs**: Run `gh pr list --repo trunk-io/docs --state open --json number,title,headRefName,url --limit 50`. +``` +Progress: +- [ ] Phase 0: Duplicate & overlap check +- [ ] Phase 1: Parse input +- [ ] Phase 2: Research (Linear, Slite, Slack, docs, PRs) +- [ ] Phase 2.5: Write sources audit file +- [ ] Phase 3: Draft documentation +- [ ] Phase 4: Branch, commit, PR +- [ ] Phase 5: Update Linear +- [ ] Phase 6: Stage outputs (Slack post, report) +- [ ] Phase 7: Clean up and summarize +``` -3. **Check for file overlap**: For any PR that looks potentially related (based on title or branch name matching the same product area), run `gh pr view --repo trunk-io/docs --json files --jq '[.files[].path]'` and compare against the draft's target files. +### Phase 0: Duplicate & Overlap Check -4. **If overlapping PRs are found**: Stop and show the user: - - The overlapping PR number, title, URL, and author - - Which target files overlap - - Ask: "PR #NNN already touches [overlapping files]. Would you like to: (a) proceed anyway (changes will likely conflict), (b) wait for that PR to merge first, or (c) skip this draft?" - - Do NOT proceed until the user responds. +Before doing any work, verify no existing PR already covers this draft. See [OVERLAP-CHECK.md](OVERLAP-CHECK.md) for the detailed check procedure. -5. **If no overlaps found**: Continue to Phase 1. +If a match or overlap is found, stop and ask the user how to proceed before continuing. ### Phase 1: Parse and Understand -1. If a notes file was provided, read it completely and extract: - - Feature/change name - - Linear ticket IDs (`TRUNK-NNNNN`) - - GitHub PR URLs or numbers - - Context links (Slack, Slite, Loom, Google Docs, etc.) - - Product area - - Change type (new feature, update, fix, deprecation, explainer) - - Key details about what changed and why - -2. If trunk2 PR numbers or a deploy tag were provided instead: - - Use `gh pr view --repo trunk-io/trunk2` to get PR details - - Extract Linear ticket IDs from PR titles and branch names +1. If a notes file was provided, read it and extract: feature name, Linear ticket IDs, GitHub PR URLs, context links, product area, change type, and key details. +2. If trunk2 PR numbers or a deploy tag were provided instead, use `gh pr view --repo trunk-io/trunk2` to get details and extract Linear ticket IDs. ### Phase 2: Research -3. **Look up Linear tickets**: Use `mcp__claude_ai_Linear__get_issue` for each ticket ID to get descriptions, status, assignee, linked PRs, and related tickets. - -4. **Search Linear for related work**: Search by feature name and product area to find engineering tickets that describe the same functionality. Collect related ticket IDs for linking later. - -5. **Search existing docs**: Use `mcp__claude_ai_trunk_docs__searchDocumentation` to find published docs on the topic. Also search the local filesystem: - - Use Glob to find related files by path - - Use Grep to find references to the feature/topic - - Read `summary.md` to understand the docs hierarchy - -6. **Read trunk2 PR diffs** (if PR numbers available): Use `gh pr diff --repo trunk-io/trunk2 --name-only` to understand what code changed, then read key files for context. - -7. **Identify gaps**: Compare what exists in the docs vs. what the notes/PRs describe. Determine: - - Does a page need updating, or does a new page need creating? - - What sections are affected? - - What's accurate vs. outdated? +3. **Linear tickets**: Use `mcp__claude_ai_Linear__get_issue` for each ticket ID. Search by feature name for related engineering tickets. +4. **Slite docs**: Search Slite for PRDs, specs, roadmap items, and knowledge base articles related to the feature. Use feature name and product area as search terms. Retrieve relevant docs for product intent, requirements, and decisions. +5. **Slack channels**: Search relevant Slack channels for recent discussion, changelogs, and context: + - `#team-flaky-tests` — Flaky Tests product discussions + - `#team-merge-queue` — Merge Queue product discussions + - Search by feature name, ticket ID, or key terms from the notes +6. **Existing docs**: Use `mcp__claude_ai_trunk_docs__searchDocumentation`, Glob, and Grep. Read `summary.md` for the docs hierarchy. +7. **trunk2 PR diffs** (if available): `gh pr diff --repo trunk-io/trunk2 --name-only`, then read key files. +8. **Gap analysis**: Compare existing docs vs. what the notes, Slite specs, and Slack threads describe. Determine whether to update or create pages. ### Phase 2.5: Generate Sources File -8. Determine the output directory from the draft filename (e.g., `.claude/drafts/flag-as-flaky.md` → `.claude/tmp/flag-as-flaky/`). All staged outputs for this run go under this directory. - - Write a sources audit trail to `.claude/tmp//sources.md`. This lets reviewers verify accuracy. Include: - - All Linear tickets found (with clickable links) - - All GitHub PRs (with links, status, key changes) - - Existing docs files relevant to this change - - Key code references from PRs - - All context links from the notes - - Related Linear tickets discovered via search +9. Write `.claude/tmp//sources.md` with all Linear tickets, GitHub PRs, Slite docs, Slack threads, existing docs, code references, and context links found during research. This is the reviewer audit trail. ### Phase 3: Draft Documentation -9. Write or edit documentation: - - **Match the tone and structure of existing Trunk docs** — read nearby files for reference - - For **new pages**: write the full page content - - For **updates**: edit the existing file(s) in place - - For **explainers**: add examples and scenarios to the relevant existing page. Use collapsible `
` blocks for edge cases. Keep happy-path guides clean. +8. Write or edit documentation: + - **Match tone and structure** of existing Trunk docs — read nearby files first + - **New pages**: write full content; **Updates**: edit in place; **Explainers**: add to relevant existing page - Update `summary.md` if adding new pages - - Writing guidelines: - - Lead with the user benefit, not implementation details - - Use present tense ("Merge Queue now supports...") - - Include practical examples and code snippets where relevant + - Lead with user benefit, not implementation details + - Use present tense, include practical examples - Don't mention internal systems (ClickHouse, Prisma, SST, Lambda) - - Use the customer's vocabulary, not engineering jargon - -### Phase 4: Create Branch, Commit, and PR -10. **Branch**: Create a branch from `main`. Determine the git username by running `git config user.name` and converting it to kebab-case (e.g., "Sam Gutentag" → `sam-gutentag`). Name the branch `/`. - - Stash any unrelated working tree changes first - - Apply only the files relevant to this change +### Phase 4: Branch, Commit, and PR -11. **Commit**: Stage the changed files and commit with a clear message. Include `Co-Authored-By: Claude Opus 4.6 ` - -12. **Push and PR**: Push to origin and create a PR via `gh pr create` with: - - **Title format:** `[TRUNK-XXXXX] Short descriptive title` (prefix with Linear ticket ID if one exists) - - Body containing: - - **Summary** — bullet list of changes - - **Linear tickets** — clickable links to all related tickets - - **Context links** — all Slack, Slite, Loom links from the notes - - **Files changed** — list of files created/modified - - **Open questions** — things that couldn't be confirmed from available context - - **Test plan** — checklist for reviewer (e.g., "check GitBook preview", "verify code example works") +9. **Branch**: From `main`. Name: `/` (username from `git config user.name`, kebab-cased). Stash unrelated changes first. +10. **Commit**: Stage changed files. Include `Co-Authored-By: Claude Opus 4.6 `. +11. **Push and PR**: `gh pr create` with structured body. See [OUTPUTS.md](OUTPUTS.md) for PR body format. ### Phase 5: Update Linear -13. **Create or update the docs ticket**: - - If a ticket exists: update description with PR link, context links, summary of changes. Add a comment with the PR link. Update status to "In Review". - - If no ticket exists: create one in Trunk Engineering team with `docs` label, assigned to "me". Include PR link and full context. - -14. **Attach context links**: For every URL from the notes (Slack, Slite, Loom, etc.), add it as an attachment on the Linear ticket with a descriptive title (e.g., `"Slack: #channel — topic"`). - -15. **Link related tickets**: For every related engineering ticket discovered during research, add a `relatedTo` relation on the docs ticket. +12. Create or update the docs ticket — add PR link, context links, change summary. Set status to "In Review". If no ticket exists, create one in Trunk Engineering with `docs` label. +13. Attach all context links (Slack, Slite, Loom) as attachments with descriptive titles. +14. Add `relatedTo` relations for every related engineering ticket found during research. ### Phase 6: Stage Outputs -16. **Slack post**: Write to `.claude/tmp//slack.md`. This file must be directly copy-pasteable into Slack with correct formatting. Use Slack's mrkdwn syntax (not Markdown): - - Bold: `*text*` (single asterisks, not double) - - Links: `` - - Bullets: `•` (bullet character, not `-`) - - No Markdown-style headers (`##`), links (`[text](url)`), or bold (`**text**`) - - Format: - ``` - *[Feature Name] — docs update ready for review* - - [1-2 sentence summary of what changed in the docs.] - - • PR: - • Linear: - - *Open questions for the team:* - • [list any items needing eng confirmation] - ``` - -17. **Review report**: Append an HTML card to `.claude/tmp/report.html` with PR link, Linear link, changes summary, review focus areas, and open questions. If the file doesn't exist, create it with basic HTML styling. +15. **Slack post**: Write to `.claude/tmp//slack.md`. See [OUTPUTS.md](OUTPUTS.md) for Slack formatting rules. +16. **Report**: Append an HTML card to `.claude/tmp/report.html`. See [OUTPUTS.md](OUTPUTS.md) for report format. ### Phase 7: Clean Up -19. Return to the original branch and restore any stashed changes. - -20. **Output summary**: Show the user: - - Branch name and PR link - - Linear ticket link - - Files changed (list) - - Open questions (numbered) - - Staged output files (slack, sources) +17. Return to original branch, restore stashed changes. +18. Show the user: branch name, PR link, Linear ticket link, files changed, open questions, staged output file paths. ## Guidelines -- **One notes file = one PR.** If a notes file describes multiple unrelated changes, flag this and ask how to split. -- **Preserve the notes file** — don't delete or modify it. It's the audit trail. -- **Ask before guessing** — if the notes are too ambiguous, output your best interpretation and list specific questions rather than making assumptions. -- **Always include PR links** in Linear comments and descriptions. -- **Match existing style** — read adjacent doc files before writing. Don't introduce new formatting conventions. -- **Keep happy paths clean** — add examples in dedicated sections, not inline with workflow steps. -- **Prioritize accuracy** — flag anything you inferred vs. confirmed in the open questions. +- **One notes file = one PR.** Flag multi-topic drafts and ask how to split. +- **Preserve the notes file** — never delete or modify it. +- **Ask before guessing** — list specific questions rather than making assumptions. +- **Always include full PR URLs** in Linear comments and descriptions. +- **Match existing style** — read adjacent docs before writing. +- **Prioritize accuracy** — flag inferred vs. confirmed items in open questions. ## Batch Processing -To process multiple notes files: -``` -Process each notes file in .claude/drafts/ one at a time. -For each: research, draft, apply, branch/PR, update Linear, then move to the next. -``` - -Each file gets its own branch (`/`), PR, Linear ticket, and output directory under `.claude/tmp/`. Process one at a time to avoid git conflicts. +Process each notes file in `.claude/drafts/` one at a time. Each gets its own branch, PR, Linear ticket, and `.claude/tmp//` directory. The skill handles git stash/restore between runs. From 855d33bfbf1c6d61af5e07973e850c5f8bf76fd5 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Thu, 12 Mar 2026 20:51:55 -0700 Subject: [PATCH 15/15] Add code-is-law principle and Slack/Slite MCP integration to write-docs skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 2 research now mandates that actual source code and PR diffs are the authoritative source — planning docs (Slite specs, PRDs, Slack threads) provide context but code wins on conflicts. Sources audit file must include code-confirmed details, a code-vs-planning-docs diff table, and open questions. Co-Authored-By: Claude Opus 4.6 --- .claude/skills/write-docs/SKILL.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.md index 56cdc7bb..b558e428 100644 --- a/.claude/skills/write-docs/SKILL.md +++ b/.claude/skills/write-docs/SKILL.md @@ -66,6 +66,8 @@ If a match or overlap is found, stop and ask the user how to proceed before cont ### Phase 2: Research +**Code is law.** Actual source code and PR diffs are the authoritative source of truth. Slite specs, PRDs, Slack threads, and other planning docs provide context, intent, and examples — but when they conflict with what the code does, the code wins. Only document what is actually implemented. + 3. **Linear tickets**: Use `mcp__claude_ai_Linear__get_issue` for each ticket ID. Search by feature name for related engineering tickets. 4. **Slite docs**: Search Slite for PRDs, specs, roadmap items, and knowledge base articles related to the feature. Use feature name and product area as search terms. Retrieve relevant docs for product intent, requirements, and decisions. 5. **Slack channels**: Search relevant Slack channels for recent discussion, changelogs, and context: @@ -73,12 +75,15 @@ If a match or overlap is found, stop and ask the user how to proceed before cont - `#team-merge-queue` — Merge Queue product discussions - Search by feature name, ticket ID, or key terms from the notes 6. **Existing docs**: Use `mcp__claude_ai_trunk_docs__searchDocumentation`, Glob, and Grep. Read `summary.md` for the docs hierarchy. -7. **trunk2 PR diffs** (if available): `gh pr diff --repo trunk-io/trunk2 --name-only`, then read key files. -8. **Gap analysis**: Compare existing docs vs. what the notes, Slite specs, and Slack threads describe. Determine whether to update or create pages. +7. **trunk2 PR diffs** (if available): `gh pr diff --repo trunk-io/trunk2 --name-only`, then read key files. When possible, also read the current source on `main` via `gh api` to confirm the latest state. +8. **Gap analysis**: Compare existing docs vs. what the code implements. Cross-reference planning docs (Slite, Slack) against code to identify discrepancies — features described in specs but not yet implemented should be flagged as open questions, not documented as existing functionality. ### Phase 2.5: Generate Sources File -9. Write `.claude/tmp//sources.md` with all Linear tickets, GitHub PRs, Slite docs, Slack threads, existing docs, code references, and context links found during research. This is the reviewer audit trail. +9. Write `.claude/tmp//sources.md` with all Linear tickets, GitHub PRs, Slite docs, Slack threads, existing docs, code references, and context links found during research. This is the reviewer audit trail. Must include: + - A **"Code-Confirmed Details"** section listing metric names, endpoint paths, auth mechanisms, etc. as they exist in the actual codebase + - A **"Differences: Code vs. Planning Docs"** table highlighting any discrepancies between what planning docs describe and what the code implements + - An **"Open Questions"** section for anything that could not be confirmed from code ### Phase 3: Draft Documentation