docs: document PR-body templates and the config auto-upgrade pass - #586
Merged
jlong merged 1 commit intoAug 25, 2026
Merged
Conversation
Two v0.9.0 features shipped without site docs. Document both, verified
against source.
- configuration/project.mdx: add a "PR-body template (pr-template.md)"
section covering the config-mode-aware location (shipped default +
per-project override), the five default sections, and how a worker
authors .shelbi/pr-body.md at handoff. Corrected the task's premise:
pr_template.rs does NO variable substitution, so the section documents
it as prose instructions and explicitly contrasts it with the
{{var}}-substituting git.branch template.
- concepts/config-upgrade.mdx (new, order 18): document the boot-time
detect -> classify (auto_heal vs needs_judgment) -> apply pass, the
events.log disclosure line, the ~/.shelbi/config-upgrade-findings.json
artifact, and the orchestrator needs-judgment handoff.
- cli/config.mdx: document the previously-undocumented `upgrade`
subcommand and its flags (--all, --apply, --needs-judgment,
--apply-finding, --format), the inspection surface for the pass.
All paths, variable/file names, flags, and the events.log body verified
against pr_template.rs, default_pr_template.md.template, config_upgrade.rs,
config.rs, serve.rs, and reload.rs. Cross-link anchor verified against the
built heading id. Site builds and lints clean; no em dashes in new prose.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
jlong
deleted the
jlong/docs-document-pr-body-templates-and-config-auto-upgrade
branch
August 25, 2026 15:47
This branch was successfully deployed
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.
Task
Two v0.9.0 features shipped without user-facing docs on the site. Document both, verified against the source.
1. Worker-authored PR bodies from a per-project template (#581)
Workers now author PR descriptions from an editable per-project template rather than a hardcoded body. Read the source before writing:
crates/shelbi-state/src/pr_template.rs(rendering + variable substitution)crates/shelbi-state/src/default_pr_template.md.template(the shipped default body)pr-template.mdunder the project dir).Document, in
site/content/docs/configuration/(extendproject.mdxnear the existing branch-template docs, or add a focused section):pr_template.rs).2. Config auto-upgrade sniffer (#550, #552, #572)
A version-agnostic validate-and-upgrade pass runs on boot: it detects drifted/legacy config, auto-heals what it safely can, and hands
needs-judgmentfindings to the orchestrator. Read the source (config_upgrade.rsand the findings JSON structure) before writing.Document, in
site/content/docs/configuration/orconcepts/:auto_healvsneeds_judgment) → apply.config-upgrade-findings.jsonfile — confirm the real name/path from code).Technical Details
Verify every path, variable name, file name, and behavior against the actual source and the CLI. Do not invent flags, paths, or placeholders — depictions of Shelbi behavior must match the code exactly.
Acceptance Criteria
configuration/: template location(s) (shipped default + per-project override), the available variables, and how workers use it at handoff.pr_template.rs,default_pr_template.md.template,config_upgrade.rs), not invented.npm run buildinsite/succeeds with no MDX errors.Auto-opened by Shelbi — review at: /Users/jlong/.shelbi/projects/shelbi/tasks/docs-document-pr-body-templates-and-config-auto-upgrade.md