Record a research / design investigation as a closed research issue

The framework's reference docs (the skill at .agents/skills/webjs/) exist ONLY to teach AI agents how to USE WebJs. They are NOT a home for research write-ups, design records, or decision histories. Polluting them rots their purpose. So a research/design/decision investigation is recorded as a GitHub issue, labeled research, with the full writeup in the body plus deep-dive comments, then CLOSED to keep the record.

The two mistakes this skill prevents

1. Do NOT write the record as a file in the framework's reference docs (no <topic>-design.md / <topic>-research.md committed under the skill at .agents/skills/webjs/ or any other doc surface). That was the #548 cleanup.
2. Do NOT bury the record as a comment on an unrelated PR or issue. It must be its own labeled research issue, or it is not filterable. (This exact mistake happened on #548. The record was first archived as a comment on the cleanup PR #552, then mis-filed as a research: PR #559, before the convention settled on a labeled issue at #560.)

Why an issue, not a PR

A research record has no code diff. A PR is a "merge this diff" object, so a research PR needs an empty-commit hack and leaves a dangling branch behind (see the now-deleted branch from #559). An issue is the native home for a writeup with threaded discussion. It is filterable by the research label, and it fits the project model where the GitHub Project board backed by issues is the source of truth. Earlier records used closed PRs (#546, #553); the convention going forward is a labeled issue. Do not convert the old PRs unless asked.

Investigate in parallel

A comparison or options analysis is multi-angle work, and each angle is an independent read: one option's codebase evidence, the prior art, the project's own constraints in AGENTS.md, what the ecosystem does. For a multi-option or multi-angle investigation, spawn one read-only Explore agent per option or angle in ONE message, each returning evidence with concrete file paths and citations, then synthesize yourself. Reads fan out; the writeup and its judgment stay with you, because the record's voice and conclusions are the caller's, not an agent vote. A single-question spike needs no fan-out. Nothing here changes WHERE the record lands (the closed research-labeled issue below).

Lifecycle: backlog item then findings in the SAME issue

Research often starts as a planned backlog item, an OPEN research-labeled issue ("research whether X") sitting in the board's Todo column. When an agent actually does the research, the findings go into that same issue, NOT a new PR:

1. The investigation thread (options weighed, dead-ends, reversals) goes in as comments.
2. The final conclusion is curated into the issue body so a reader gets the answer without scrolling the whole thread.
3. When research concludes, close the issue. The question and its answer now live together, filterable by the label.

So there are two entry points, same destination:

• No issue exists yet (a record being captured after the fact, or relocated out of the reference docs): create the research-labeled issue with the writeup, then close it.
• A backlog research issue already exists: append findings to it (comments + curated body), then close it. Do not open a PR.

The one carve-out where a PR is right

If the research produced actual code worth showing (a throwaway spike or prototype), open a draft PR for that code and link it from the research issue. The decision write-up still lands in the issue body and comments, and the spike PR is closed (not merged) unless it graduates into real implementation, which is then a separate webjs-file-issue task. A pure no-code record never gets a PR.

Inputs

Extract from the user's request:

• A title prefixed research: (lowercase), short and descriptive of the question or decision.
• A body capturing the full record: the question/problem, the options compared, the decision and its rationale, and any "what shipped vs what was recommended" reversal. If the record is being relocated out of the reference docs, recover the original file content from git history and preserve it verbatim in the body.
• Deep-dive comments for threaded detail (key reversals, the motivating bug, cross-references to related issues/PRs).

Steps

Every gh issue * call below is REST (gh api), because that porcelain goes through GraphQL, whose point budget is routinely spent here, and writing the record IS this skill's whole deliverable, so it must not be the thing a spent budget blocks. The one porcelain call kept is gh label create in step 1, which is already REST underneath (see the note there). See .claude/gh-budget.md. Build every body payload with jq -n --rawfile so backticks and $ in the prose never reach the shell.

1. Ensure the research label exists (one-time):

   gh api "repos/webjsdev/webjs/labels?per_page=100" --jq '[.[].name] | index("research")'
   # if that prints null:
   gh label create research --repo webjsdev/webjs --color 5319e7 \
     --description "Research/design/decision record (no code); filter these to read design history"

   The read is REST because gh label list goes through GraphQL. The create stays on the porcelain because gh label create does NOT: it issues a plain POST /repos/{owner}/{repo}/labels, so there is nothing to save by rewriting it and the shorter form is easier to read.

2. Find or create the issue. If a backlog research issue already exists for this question, use it. Otherwise create one:

   jq -n --rawfile b /tmp/research-record.md \
     '{title:"research: <question or decision>", body:$b, labels:["research"]}' > /tmp/rec.json
   gh api -X POST repos/webjsdev/webjs/issues --input /tmp/rec.json --jq '"\(.number) \(.html_url)"'

   When appending to an existing backlog issue, also curate the final conclusion into its body so the answer is readable without the whole thread:

   jq -n --rawfile b /tmp/research-record.md '{body:$b}' > /tmp/rec-body.json
   gh api -X PATCH repos/webjsdev/webjs/issues/<n> --input /tmp/rec-body.json --jq .number
   # confirm the label is present (adding one already on the issue is a no-op):
   gh api -X POST repos/webjsdev/webjs/issues/<n>/labels -f 'labels[]=research' --jq '[.[].name]|join(",")'

3. Add deep-dive comments for the threaded detail:

   jq -n --rawfile b /tmp/deep-dive.md '{body:$b}' > /tmp/rec-comment.json
   gh api -X POST repos/webjsdev/webjs/issues/<n>/comments --input /tmp/rec-comment.json --jq .html_url

4. Close the issue as completed (it is a record, not open work):

   gh api -X PATCH repos/webjsdev/webjs/issues/<n> -f state=closed -f state_reason=completed \
     --jq '"\(.state)/\(.state_reason)"'

5. Report the issue number and confirm it carries the research label.

After the record

The actual implementation that the research points to is separate tracked work. File it via the webjs-file-issue skill as its own actionable issue. Keep the research record (the "why") and the implementation task (the "what to build") as distinct issues so the board reads cleanly.

Verify

# All research records, filterable by the label:
gh api "repos/webjsdev/webjs/issues?labels=research&state=all&per_page=100" \
  --jq '.[] | select(has("pull_request") | not) | "#\(.number) \(.title)"'

REST rather than gh issue list, which goes through GraphQL. See .claude/gh-budget.md for the rule and the full substitution table. The pull_request filter is not optional: the REST issues endpoint returns PRs alongside issues.