docs: add tutorial guide for the Bug Fix workflow#77
Merged
jwm4 merged 6 commits intoambient-code:mainfrom Mar 19, 2026
Merged
Conversation
User-facing tutorial covering how to start a bugfix session, choose a model, walk through each workflow phase, and use speedrun mode. Written for end users, not workflow developers. Made-with: Cursor
WalkthroughAdds a new Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Cover GitHub Action, acpctl CLI, MCP server, and SDKs with examples specific to the Bug Fix workflow. Made-with: Cursor
Lead with the raw curl example showing the actual backend API call, explain each field (especially activeWorkflow which loads the workflow), keep GitHub Action as a convenience wrapper, and demote unverified tools to brief pointers. Made-with: Cursor
Made-with: Cursor
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/bugfix-tutorial.md`:
- Around line 78-85: The "Workflow Phases" section currently describes 8 phases
but the startup greeting shows 6; either update this section to match the
canonical 6-phase model shown at startup (rename and reorder phases to match the
startup prompt) or explicitly call out that the Review/PR steps are "extended
phases beyond the 6-phase startup experience" by adding a short clarifying note
under the header and labeling the extra steps (e.g., "Review/PR — extended
phase"). Ensure the wording references the startup prompt terminology so readers
see the alignment.
- Around line 161-175: The Review section (header "Review" with the "Command:
/review" snippet) is missing the artifact output path; add a short "Outputs:" or
"Artifacts:" line mirroring other phase sections that specifies the Review
report file path (e.g., "review-report.md" or the project's canonical review
artifact name) so readers can find the generated Review report; keep wording and
formatting consistent with other phases' "Outputs" lines and place it directly
under the existing Review description or verdict list.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: f153eeac-7738-4bf9-b637-464d8a647840
📒 Files selected for processing (1)
docs/bugfix-tutorial.md
kami619
reviewed
Mar 19, 2026
kami619
reviewed
Mar 19, 2026
kami619
reviewed
Mar 19, 2026
kami619
reviewed
Mar 19, 2026
- Note that 8 phases include Review and PR beyond the 6-phase greeting - Add Review artifact path (artifacts/bugfix/review/verdict.md) - Explain how to interrupt speedrun and what causes it to stop - Mark Automation section as for advanced users Made-with: Cursor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/bugfix-tutorial.md`:
- Line 186: Remove the incorrect artifact reference
"artifacts/bugfix/review/verdict.md" from the tutorial's Report line in
docs/bugfix-tutorial.md; ensure the Review phase text matches the workflow spec
by deleting that Report entry so the tutorial aligns with the workflow/bugfix
README statement "Review findings reported inline to the user (not a file)".
- Around line 84-89: The tutorial's phase count and Review artifact claim are
inconsistent with the canonical workflow docs: update bugfix-tutorial.md to
match the actual workflow by including the Assess phase (so both documents
describe eight phases consistently) and remove or correct the incorrect Review
artifact reference to "artifacts/bugfix/review/verdict.md"; instead state the
Review output is reported inline per the bugfix README and CLAUDE.md. Locate the
phase list and the Review description in bugfix-tutorial.md, add Assess to the
numbered phases where missing, and change the artifact path line to reflect
inline reporting (or point to the correct artifact location if README/CLAUDE.md
indicate a different file).
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 1441d68d-0cb6-42b2-8c59-a735669e4a66
📒 Files selected for processing (1)
docs/bugfix-tutorial.md
- Add Phase 1: Assess to bugfix README (was missing) - Renumber all phases (now 1-8) - Fix Review output path in README (now artifacts/bugfix/review/verdict.md) - Update Quick Start to reference /assess instead of /reproduce - Minor copy fixes in tutorial Made-with: Cursor
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
workflows/bugfix/README.md (3)
23-37:⚠️ Potential issue | 🟠 MajorDirectory structure is missing the new Assess command/skill entries.
The tree still omits
.claude/commands/assess.mdand.claude/skills/assess/SKILL.md, which now makes the structure section inaccurate after introducing Phase 1 Assess.Suggested doc patch
│ ├── commands/ # Slash commands (thin wrappers → skills) +│ │ ├── assess.md │ │ ├── reproduce.md │ │ ├── diagnose.md @@ │ └── skills/ # Detailed process definitions +│ ├── assess/SKILL.md │ ├── reproduce/SKILL.md │ ├── diagnose/SKILL.mdAs per coding guidelines, "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@workflows/bugfix/README.md` around lines 23 - 37, The README tree is missing the newly added Assess phase entries; update the directory structure section to include .claude/commands/assess.md under the commands list and .claude/skills/assess/SKILL.md under the skills list so the document matches the Phase 1 Assess changes—locate the commands block that lists reproduce.md..pr.md and insert assess.md in the appropriate order, and similarly add assess/SKILL.md to the skills block that lists reproduce/SKILL.md..pr/SKILL.md.
180-196:⚠️ Potential issue | 🟠 MajorQuick Start and Scenario 1 conflict on the first phase.
Line 180 says to start with
/assess, but Scenario 1 still states “Starts with /reproduce.” This creates contradictory onboarding guidance in the same document.Suggested doc patch
-Workflow: Starts with /reproduce to confirm the bug +Workflow: Starts with /assess to analyze the report and plan reproduction +→ /reproduce to confirm the bug → /diagnose to find root causeAs per coding guidelines, "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@workflows/bugfix/README.md` around lines 180 - 196, The Quick Start and Scenario 1 conflict: Quick Start instructs to begin with the /assess command but Scenario 1 still shows “Starts with /reproduce”; update the document so both places use the same first phase (pick one — e.g., change Scenario 1’s “Starts with /reproduce” to “Starts with /assess” or change the Quick Start to /reproduce) and ensure any subsequent phase sequence (the → /diagnose → /fix ... list) remains consistent with the chosen starting command; update occurrences of the commands /assess and /reproduce in the README to match.
245-264:⚠️ Potential issue | 🟠 MajorArtifacts index is stale relative to the phase outputs.
The artifact tree does not include
artifacts/bugfix/reports/assessment.mdorartifacts/bugfix/review/verdict.md, even though they are now documented as phase outputs. This hurts artifact discoverability.Suggested doc patch
artifacts/bugfix/ ├── reports/ # Bug reproduction reports +│ ├── assessment.md │ └── reproduction.md ├── analysis/ # Root cause analysis │ └── root-cause.md @@ +├── review/ # Review verdict and findings +│ └── verdict.md ├── docs/ # Documentation and release notesAs per coding guidelines, "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@workflows/bugfix/README.md` around lines 245 - 264, The artifacts index in the README’s artifact tree is missing two phase outputs; update the listing under artifacts/bugfix/ to include the missing entries artifacts/bugfix/reports/assessment.md and artifacts/bugfix/review/verdict.md so the tree reflects current phase outputs (add a reports/assessment.md entry under the reports node and add a review/ directory with verdict.md under the top-level artifacts/bugfix/ tree) to restore discoverability.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Outside diff comments:
In `@workflows/bugfix/README.md`:
- Around line 23-37: The README tree is missing the newly added Assess phase
entries; update the directory structure section to include
.claude/commands/assess.md under the commands list and
.claude/skills/assess/SKILL.md under the skills list so the document matches the
Phase 1 Assess changes—locate the commands block that lists reproduce.md..pr.md
and insert assess.md in the appropriate order, and similarly add assess/SKILL.md
to the skills block that lists reproduce/SKILL.md..pr/SKILL.md.
- Around line 180-196: The Quick Start and Scenario 1 conflict: Quick Start
instructs to begin with the /assess command but Scenario 1 still shows “Starts
with /reproduce”; update the document so both places use the same first phase
(pick one — e.g., change Scenario 1’s “Starts with /reproduce” to “Starts with
/assess” or change the Quick Start to /reproduce) and ensure any subsequent
phase sequence (the → /diagnose → /fix ... list) remains consistent with the
chosen starting command; update occurrences of the commands /assess and
/reproduce in the README to match.
- Around line 245-264: The artifacts index in the README’s artifact tree is
missing two phase outputs; update the listing under artifacts/bugfix/ to include
the missing entries artifacts/bugfix/reports/assessment.md and
artifacts/bugfix/review/verdict.md so the tree reflects current phase outputs
(add a reports/assessment.md entry under the reports node and add a review/
directory with verdict.md under the top-level artifacts/bugfix/ tree) to restore
discoverability.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: c1f14b00-9a66-43a7-8f65-780f0e089ebe
📒 Files selected for processing (2)
docs/bugfix-tutorial.mdworkflows/bugfix/README.md
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
3 participants
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
docs/bugfix-tutorial.mdfor the Bug Fix workflowTest plan
Made with Cursor