chore(skills): rework /issue into a confidence-scored Q&A flow (tldraw#9034)

In order to make `/issue` useful for quick, low-context reports without
sending downstream agents past missing intent, this PR creates issues
immediately and then matures them through a confidence-scored follow-up
flow.

The old flow front-loaded codebase research before creating the issue.
The new flow inverts that: create the issue from the user's initial
description, read back the problem in product terms, score how complete
the captured intent is, and ask the questions that would fill the gaps —
updating the issue in place as answers arrive.

### What changes

- **Create first, mature later.** The skill creates the issue right away
so the user can track it, rather than researching the codebase to death
first.
- **Standard body shape.** The body starts with the user's verbatim
description, then a short product-facing **readback** of the problem, a
numbered list of **Open questions**, and a plain-text **Confidence**
status line (e.g. `Confidence: 84%, ready to get started.`).
- **Light investigation.** Codebase searching is kept to just enough to
ground the confidence score and ask sharp questions. Anything answerable
from the code should not become an open question, and implementation
breadcrumbs (file paths, function names, fix recipes) stay out of the
body unless the user asks for them.
- **Q&A loop.** As the user answers, the issue is updated via `gh issue
edit`: answers are written beneath each question, the readback is
revised, the confidence line is recomputed, and the issue framing
(title, type, labels) can be adjusted if an answer changes what the
issue is.
- **Critical vs. deferred questions.** Questions prefixed `Critical:`
block readiness and cannot be skipped. Non-critical questions the user
chooses not to answer are marked `_Deferred by user; not blocking
implementation._` and do not block.
- **Downstream guardrails.** The `take` skill now treats unresolved
`Critical:` questions, `_Awaiting answer._` placeholders, and the `More
Info Needed` label as blockers before implementation.
- **Issue type helper.** `skills/issue/scripts/set-issue-type.sh` sets
GitHub issue types via GraphQL because `gh issue create --type` is
unreliable across versions.

### Change type

- [x] `other`

### Test plan

1. Read the `/issue` workflow and confirm follow-up answers retrigger
the skill and update the issue body in place.
2. Read the `write-issue` standards and confirm the readback, open
questions, and deferred-question conventions are documented.
3. Read the `take` workflow and confirm unresolved agent-drafted
questions block implementation.
4. Run `git diff --check`.

### Code changes

| Section        | LOC change |
| -------------- | ---------- |
| Config/tooling | +110 / -23 |

Author: steveruizok

skills/issue/SKILL.md

@@ -1,62 +1,101 @@
 ---
 name: issue
-description: Create and research a GitHub issue in the tldraw repository from a user description. Use when the user invokes issue, asks to create an issue, report a bug, file a feature request, or add research to a new issue.
+description: Create a GitHub issue in the tldraw repository from a user description, then mature it through follow-up questions. Use when the user invokes issue, asks to create an issue, report a bug, file a feature request, or answers follow-up questions for an issue created by this skill.
 ---
 
 # Issue
 
-Create a GitHub issue on `tldraw/tldraw` from a user description, then research it.
+Create a GitHub issue on `tldraw/tldraw` from a user description, then interrogate the user to capture enough of their intent for the issue to be worked on.
 
 Use `../write-issue/SKILL.md` as the standards reference for issue titles, bodies, types, labels, and triage conventions.
 
-At the top of the issue, include the user's original description verbatim. Annotate it with the human emoji, separated from your work by a horizontal rule. Example:
+The goal is not to research the codebase to death. It is to capture the user's full intent and context in the issue, so that whoever (or whatever) picks it up later has what they need. You do this by creating the issue immediately, writing a brief readback of the problem, and then asking the user the questions that would sharpen that understanding.
+
+## Issue body shape
+
+The body always starts with the user's original description, verbatim, annotated with the human emoji and separated from the rest by a horizontal rule:
 
 ```
-🧑: {user_description}
+🗣️: {user_description}
 
 ---
+
+{two to five sentences that read back your understanding of the problem, expected behavior, and scope}
+
+## Open questions
+
+1. **{question}**
+   _Awaiting answer._
+2. **{question}**
+   _Awaiting answer._
+
+Confidence: {n}%, {ready_status}.
 ```
 
+- The readback paragraph is the agent's understanding of the problem. It should be short enough for the user to quickly correct, but specific enough to make the intended behavior clear. Keep it product-facing: no code blocks, no long implementation analysis, and no line-by-line diagnosis.
+- Do not include implementation breadcrumbs in the issue body by default. Avoid file paths, function names, line numbers, code snippets, likely causes, and fix recipes unless the user explicitly asks to include them. Whoever picks up the work can rediscover that technical context.
+- Keep product intent ahead of code diagnosis. The issue should record what the user wants, what they observed, and what scope or behavior they confirmed. Do not present a root cause or fix direction as fact unless the user has confirmed that framing.
+- Each open question targets a specific gap in intent or context. Avoid questions you could answer yourself by looking at the code.
+- Keep questions atomic. Do not bundle user-intent questions with implementer-verifiable technical checks. If the user answers only part of a compound question, keep the remaining part open only when it still needs the user's intent or context.
+- Prefer omitting implementer-verifiable unknowns over asking the user to verify them. Ask only when the user's own context or intent matters.
+- Prefix a question with `Critical:` inside the bold, e.g. `**Critical: Which package should we rename?**`, only when it is genuinely blocking — the issue cannot be worked on at all until it is answered. Most issues have none; do not inflate ordinary gaps into critical ones.
+- As the user answers, replace `_Awaiting answer._` with their answer (lightly cleaned up) directly beneath the question, revise the readback, and add or drop unanswered questions as needed.
+- If the user chooses not to answer a non-critical question, replace `_Awaiting answer._` with `_Deferred by user; not blocking implementation._`. Do not use this for critical questions.
+- The confidence line is a plain-text status line, not a section. It reflects whether the issue contains enough of the user's context and intent to be worked on, not confidence in the eventual fix. Use a short status phrase such as `ready to get started`, `still need more information`, or `blocked on a critical question`.
+
 ## Workflow
 
 1. Gather context:
    - User's issue description.
    - Current branch: `git branch --show-current`.
    - Recent issues: `gh issue list --repo tldraw/tldraw --limit 5 --json number,title --jq '.[] | "#\(.number) \(.title)"'`.
-2. Do a quick codebase investigation:
-   - Search for relevant files, functions, or patterns mentioned in the description.
-   - Identify likely affected packages, apps, or examples.
-   - Note obvious causes, related issues, or existing code paths.
+2. Do a lightweight triage check, not implementation research:
+   - Look for duplicate or closely related issues.
+   - Use repo context only to choose issue type, labels, milestone, and broad affected area.
+   - If a shallow code search is needed to avoid asking a bad question, do it, but do not add file paths, function names, line numbers, code snippets, likely causes, or fix recipes to the issue body.
+   - Anything you can answer yourself from repo context should not become an open question.
 3. For visual bugs, identify a reproduction target when possible:
    - Examples app: `localhost:5420` from `yarn dev`.
    - tldraw.com app: `localhost:3000` from `yarn dev-app`.
    - Docs site: `localhost:3001` from `yarn dev-docs`.
-   - If screenshots are useful but not feasible locally, ask the user for screenshots and specific reproduction details.
-4. Write the issue title and body using `../write-issue/SKILL.md`.
+   - If the user provided an image and you have a path or URL for it, embed or attach it in the GitHub issue.
+   - If the image is visible only in the chat and cannot be attached, describe it as visual context. Do not write "screenshot attached" unless the issue actually contains the image.
+   - If screenshots are useful but not feasible locally and the user has not provided one, make a screenshot request one of your open questions.
+4. Write the issue title and body using `../write-issue/SKILL.md`. The body follows the shape above: verbatim description, readback paragraph, open questions, and the confidence status line.
 5. Create the issue:
 
 ```bash
 gh issue create --repo tldraw/tldraw --title "..." --body "..."
 ```
 
-6. Set the issue type through GitHub GraphQL when possible, since `gh issue create --type` is not reliable across versions.
+6. Set the issue type (`Bug`, `Feature`, `Example`, or `Task`) — `gh issue create --type` is unreliable, so use the script:
+
+```bash
+skills/issue/scripts/set-issue-type.sh <issue-number> <type-name>
+```
 7. Assign a milestone only when there is a clear fit:
    - `Improve developer resources` for examples, documentation, comments, starter kits, and `npm create tldraw`.
    - `Improve automations` for GitHub Actions, review bots, CI/CD, and automation work.
-8. Share the issue URL with the user immediately after creation.
-9. Do deeper research after creation:
-   - Identify relevant files and line numbers.
-   - Explain the root cause for bugs.
-   - Summarize architecture context and related code.
-   - Note edge cases, testing needs, and likely implementation risks.
-10. Add the research as an issue comment:
+8. Manage the `More Info Needed` label consistently:
+   - Add it only when a critical question is unanswered or the confidence line says the issue still needs more information.
+   - Remove it when the issue is ready to get started, even if non-blocking considerations remain.
+9. Respond to the user with the issue URL, your readback, and the list of open questions. Ask them directly, leading with any critical question.
+10. Interrogate the user. After each reply:
+   - Update the issue body: write the user's answer beneath the relevant question, revise the readback, recompute the confidence status line, and add or drop questions as their answers reveal new gaps or close old ones.
+   - Reconsider the issue's framing in light of the new context. If an answer changes what the issue actually is, update the title (`gh issue edit --title`), the issue type (the script from step 6), or its labels to match — for example, when a reported bug turns out to be a feature request, or the real problem is narrower than the title suggests.
+   - If the user corrects your framing, especially with phrases like "actually" or "well actually," treat it as a signal to rewrite the readback around the corrected distinction. Remove or soften obsolete assumptions before asking more questions.
 
 ```bash
-gh issue comment <issue-number> --repo tldraw/tldraw --body "..."
+gh issue edit <issue-number> --repo tldraw/tldraw --body "..."
 ```
 
+   - Keep going, one round at a time, until the readback and question answers hold enough of the user's intent and context to be worked on.
+11. The issue is ready when no critical question is unanswered and it holds enough of the user's intent to be worked on. Never declare it ready while a critical question is open, regardless of how complete the rest is.
+   - Low-priority questions the user has chosen to defer may stay open; readiness does not require answering them. Mark them as `_Deferred by user; not blocking implementation._` rather than leaving `_Awaiting answer._` placeholders.
+   - When ready, remove the `More Info Needed` label, tell the user the issue can be picked up, and set the confidence line accordingly, e.g. `Confidence: 84%, ready to get started.` Leave the readback, every question, and the confidence line in the issue as a record of the discussion. Do not delete them.
+
 ## Rules
 
-- Always create the issue before doing deep research so the user can track it.
-- Follow `../write-issue/SKILL.md` for all issue content standards.
-- Do not include AI attribution in issue titles, bodies, comments, or metadata.
+- Always create the issue before interrogating the user, so they can track it from the first reply.
+- Ask only questions that capture the user's intent or context. Do not offload work you could do yourself.
+- Update the issue after every reply rather than batching answers at the end.

skills/issue/scripts/set-issue-type.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Set a GitHub issue's type (Bug, Feature, Example, Task, ...) via GraphQL.
+# The `gh issue create --type` flag is not reliable across versions, so we
+# resolve the issue and type node IDs and run the updateIssueIssueType mutation.
+#
+# Usage: set-issue-type.sh <issue-number> <type-name> [owner/repo]
+#   set-issue-type.sh 1234 Bug
+#   set-issue-type.sh 1234 Feature tldraw/tldraw
+set -euo pipefail
+
+issue_number="${1:?usage: set-issue-type.sh <issue-number> <type-name> [owner/repo]}"
+type_name="${2:?usage: set-issue-type.sh <issue-number> <type-name> [owner/repo]}"
+repo="${3:-tldraw/tldraw}"
+owner="${repo%/*}"
+name="${repo#*/}"
+
+issue_id=$(gh issue view "$issue_number" --repo "$repo" --json id --jq '.id')
+
+type_id=$(gh api graphql \
+  -f owner="$owner" -f name="$name" \
+  -f query='query($owner:String!,$name:String!){repository(owner:$owner,name:$name){issueTypes(first:20){nodes{id name}}}}' \
+  --jq ".data.repository.issueTypes.nodes[] | select(.name == \"$type_name\") | .id")
+
+if [ -z "$type_id" ]; then
+  echo "error: no issue type named '$type_name' in $repo" >&2
+  echo "available types:" >&2
+  gh api graphql -f owner="$owner" -f name="$name" \
+    -f query='query($owner:String!,$name:String!){repository(owner:$owner,name:$name){issueTypes(first:20){nodes{name}}}}' \
+    --jq '.data.repository.issueTypes.nodes[].name' >&2
+  exit 1
+fi
+
+gh api graphql \
+  -f issueId="$issue_id" -f issueTypeId="$type_id" \
+  -f query='mutation($issueId:ID!,$issueTypeId:ID!){updateIssueIssueType(input:{issueId:$issueId,issueTypeId:$issueTypeId}){issue{number issueType{name}}}}' \
+  --jq '"set #\(.data.updateIssueIssueType.issue.number) type to \(.data.updateIssueIssueType.issue.issueType.name)"'

skills/take/SKILL.md

@@ -42,6 +42,8 @@ Read the full issue and comments. Identify:
 - Technical notes and affected files.
 - Relevant discussion or clarifications.
 
+Agent-drafted issues may include `## Confidence` and `## Open questions` sections. Treat any unanswered `Critical:` question, `_Awaiting answer._` entry, or `More Info Needed` label as a blocker unless codebase exploration proves the intended behavior is unambiguous. Resolve blockers with the user before implementing; non-critical questions marked `_Deferred by user; not blocking implementation._` may remain open.
+
 If the issue lacks detail, explore the codebase before deciding whether implementation is safe.
 
 ### 3. Assign the issue
@@ -103,7 +105,7 @@ End with:
 
 ## Rules
 
-- Ask the user when requirements are unclear.
+- Ask the user when requirements are unclear. Do not implement past unanswered critical questions or unresolved `_Awaiting answer._` placeholders.
 - Do not guess at unspecified product behavior.
 - Keep the implementation scoped to the issue.
 - Never include AI attribution in commits, issues, or PRs.

skills/write-issue/SKILL.md

@@ -90,6 +90,16 @@ Use sparingly (1-2 per issue) for metadata, not categorization.
 3. Suggested approach
 4. Which example category it belongs to
 
+### Agent-drafted issues (problem readback and open questions)
+
+Issues created by the `/issue` skill capture the user's intent over a short interrogation, so they carry an unheaded readback paragraph beneath the verbatim description, followed by open questions and a confidence status line at the bottom:
+
+- **Problem readback** - A brief, unheaded paragraph that states the agent's interpretation of the problem, expected behavior, and scope. It should be easy for the user to correct. Keep it product-facing: no code blocks, no long implementation analysis, no file paths, no function names, no line numbers, and no fix recipes unless the user explicitly asks for them.
+- **Open questions** - A numbered list of the specific gaps in intent or context still worth asking the user about. Answers are written beneath each question as the user replies, and the readback is revised each round. A question prefixed with `Critical:` is genuinely blocking — the issue cannot be worked on until it is answered. Most issues have none. Non-critical questions the user chooses not to answer are marked `_Deferred by user; not blocking implementation._`.
+- **Confidence line** - A plain-text line at the bottom, not a section heading, such as `Confidence: 84%, ready to get started.` or `Confidence: 42%, still need more information.` It reflects whether the issue has enough of the user's intent and context to work on, not confidence in the eventual fix.
+
+Leave the readback, open questions, and confidence line in the issue once interrogation is complete. The answered questions are a record of the discussion that produced the issue, so keep them rather than deleting them — mark questions resolved in place and keep the final readback as the issue's concise problem statement.
+
 ## Triage workflow
 
 ### New issues