docs(readme): lead with what burn can do, walk every subcommand#146
Open
willwashburn wants to merge 1 commit intomainfrom
Open
docs(readme): lead with what burn can do, walk every subcommand#146willwashburn wants to merge 1 commit intomainfrom
willwashburn wants to merge 1 commit intomainfrom
Conversation
Restructure the README around capability discovery. The previous version led with philosophy and stamping internals; the new version leads with a quick-start (wrap → query) and then walks every burn subcommand (summary, by-tool, waste, waste --patterns, compare, diagnose, context, context advise, limits, plans, watch, mcp-server, maintenance) using real output from a live ledger so a reader can see the shape of each answer before running anything. Stamping, env-var contract, hook-based ingest, data model, content sidecar, activity classification, packages, and pricing are kept but moved below the walkthrough so the first scroll answers "what does this thing actually do." Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| | `coding` | `Edit` / `Write` / `NotebookEdit` with no stronger keyword signal | | ||
| | `docs` | Edit turn where **every** edited file is a doc (`*.md`, `*.mdx`, `*.rst`, `*.adoc`, `*.txt`, `README*`, `CHANGELOG*`, anything under `docs/`) | | ||
| | `debugging` | Edit turn where prompt mentions bug/error/crash/traceback, or any tool call errored this turn, or the turn contains ≥2 edit→bash→edit retry cycles | | ||
| | `docs` | Edit turn where every edited file is a doc (`*.md`, `*.rst`, `README*`, anything under `docs/`) | |
Contributor
There was a problem hiding this comment.
🟡 docs activity category description drops recognized file extensions and patterns
The rewritten docs row in the activity classification table now lists only *.md, *.rst, README*, and docs/ — but the actual classifier in packages/reader/src/classifier.ts:177-186 (DOC_FILE_PATTERNS) also matches *.mdx, *.adoc, *.txt, and CHANGELOG*. The old README correctly listed all of these. Since AGENTS.md:79 directs users to "read README.md first" for architecture/API surface questions, and this table is the user-facing description of what burn compare buckets each turn into, the omission will mislead users about which files trigger the docs category.
Suggested change
| | `docs` | Edit turn where every edited file is a doc (`*.md`, `*.rst`, `README*`, anything under `docs/`) | | |
| | `docs` | Edit turn where every edited file is a doc (`*.md`, `*.mdx`, `*.rst`, `*.adoc`, `*.txt`, `README*`, `CHANGELOG*`, anything under `docs/`) | |
Was this helpful? React with 👍 or 👎 to provide feedback.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
wrap → query) and a walkthrough of everyburnsubcommand using real output from a live ledger.summary,by-tool,waste,waste --patterns,compare,diagnose,context,context advise,limits,plans,watch,mcp-server, plus the maintenance commands.Test plan
npx markdown-link-check README.md(or open in GitHub preview) — no broken links.burn --helpand produces output of the shape claimed when run on a populated ledger.TurnRecordschema, content-sidecar modes, activity-classification table, packages list, reasoning-pricing semantics, and pricing-update instructions are all preserved.🤖 Generated with Claude Code