assess

name	assess
description	Understand the bug report and propose a plan before taking action.

Assess Bug Report Skill

You are reviewing a bug report to build a shared understanding with the user before any work begins. This is the first phase of the bugfix workflow. Your job is to read, think, and explain — not to start fixing anything.

Your Role

Read the bug report (issue, description, conversation context) and present your understanding back to the user. Identify gaps. Propose a plan. Let the user correct you before you invest effort in the wrong direction.

Critical Rules

• Do not start reproducing, diagnosing, or fixing. This phase is analysis and planning only.
• Do not run the project's code or tests. You may clone and read code, but do not execute it yet.
• Be honest about uncertainty. If the report is vague, say so.

Process

Step 1: Gather the Bug Report

Collect all available information about the bug:

• If the user provided a GitHub issue URL, fetch it:

gh issue view NUMBER --repo OWNER/REPO --json title,body,labels,comments,state

• If the user described the bug in conversation, use that context
• Check if any prior artifacts exist (from a previous session or phase)

Step 2: Ensure the Repository Is Available

Check if the project repository is already accessible:

# Check common locations
ls /workspace/repos/ 2>/dev/null
ls /workspace/artifacts/ 2>/dev/null

• If the repo is already present (e.g., mounted via add_dirs), note its path
• If not, clone it:

gh repo clone OWNER/REPO /workspace/repos/REPO

• If the issue references specific PRs, files, or code paths, read them now to inform your assessment

This is read-only exploration — understand the code, don't change it.

Step 3: Check for Existing Work

Before investing effort, check whether this bug is already being addressed:

• Check for linked PRs on the issue:

gh issue view NUMBER --repo OWNER/REPO --json body,comments --jq '[.body, .comments[].body] | join("\n")' | grep -i "pull\|PR\|#"

• Scan recent PR titles for overlap:

gh pr list --repo OWNER/REPO --state open --limit 30 --json number,title,headRefName --jq '.[] | "\(.number)\t\(.title)"'

Skim the titles for anything related to the bug's component, error, or symptoms. If a PR looks relevant, read its description before proceeding.

• Check for duplicate or related issues:

gh issue list --repo OWNER/REPO --state open --limit 30 --json number,title --jq '.[] | "\(.number)\t\(.title)"'

If you find an open PR that appears to directly address this bug, stop here and use AskUserQuestion before continuing the assessment. Present the options:

• "PR #N appears to address this bug — review it instead of starting fresh"
• "PR #N is related but doesn't fully cover it — continue with assessment"
• "Not sure if PR #N is relevant — continue with assessment"

This gate applies in both normal and speedrun mode. Do not continue to Step 4 until the user responds. The AskUserQuestion tool triggers platform notifications so the user knows you need their input.

If duplicate or related issues are found (but no PR), note them in the assessment and continue — these inform the assessment but don't block it.

If no existing work is found, note that and continue.

Step 4: Summarize Your Understanding

Present a clear, concise summary to the user covering:

• What the bug is: One or two sentences describing the problem as you understand it
• Where it occurs: Which component, service, or area of the codebase is affected (if identifiable)
• Who reported it and when: Context about the report (issue number, reporter, date, labels)
• Severity/impact: Your assessment of how serious this is, based on the information available

Step 5: Identify What You Know vs. What's Missing

Be explicit about gaps:

• Available information: What the report tells you (steps to reproduce, error messages, environment details, screenshots, logs)
• Missing information: What you'd need to know but don't have (e.g., "The report doesn't mention which version this occurs on" or "No error message was provided")
• Assumptions: Any assumptions you're making — call them out so the user can confirm or correct them

Step 6: Propose a Reproduction Plan

Based on your understanding, outline how you would approach reproduction:

• What environment or setup is needed
• What specific steps you would follow
• What you would look for to confirm the bug exists
• Any tools, test data, or access you'll need

If the bug seems straightforward, the plan can be brief. If it's complex or ambiguous, be thorough.

Step 7: Present to the User

Deliver your assessment in this structure:

## Bug Assessment

**Issue:** [title or one-line summary]
**Source:** [issue URL, conversation, etc.]

### Existing Work
[Any related PRs, duplicate issues, or prior attempts — or "None found"]

### Understanding
[Your 2-3 sentence summary of the bug]

### Available Information
- [What you know]

### Gaps
- [What's missing or unclear]

### Assumptions
- [Any assumptions you're making]

### Proposed Reproduction Plan
1. [Step one]
2. [Step two]
3. ...

### Questions
- [Anything you'd like the user to clarify before proceeding]

Be direct. If the bug report is clear and complete, say so. If it's vague or missing critical details, say that too.

If the bug doesn't actually apply, say so clearly and present options:

• "This issue doesn't affect your project — here's why. Want to close it?"
• "The reported issue doesn't apply directly, but here's a related improvement we could make (with trade-offs): ..."
• "This appears to be a duplicate of #N — should we close this one?"

Do not proceed to fix something you've concluded isn't broken. Present your finding and let the user decide.

Step 8: Write the Assessment Artifact

Save your assessment to artifacts/bugfix/reports/assessment.md so that subsequent phases (and speedrun resumption) can detect that this phase is complete. The file should contain the same content you presented to the user in Step 7.

Output

• Assessment presented directly to the user (inline)
• Assessment saved to artifacts/bugfix/reports/assessment.md
• The project repository cloned and available for subsequent phases
• No code is executed, no files in the project are modified

When This Phase Is Done

Report your assessment:

• Your understanding of the bug
• Key gaps or risks identified
• Your proposed plan