webjs-research-record git:20260617.3dae75dA

Immutable. This exact content never changes and is served at /api/v1/blob/7f344c1d65673033.

---
name: webjs-research-record
description: Use this skill to record a research, design, or decision investigation on the webjsdev/webjs project. A research/design record is a CLOSED GitHub issue labeled `research` (the durable writeup lives in the issue body plus comments), never a file under `agent-docs/` and never a comment buried on an unrelated PR. Trigger phrases include "research whether X", "investigate X", "evaluate X vs Y", "compare A and B and decide", "design record for Z", "decision record", "write up the design", "spike X", or any natural-language ask whose deliverable is a writeup of a comparison, options, or a decision rather than shipped code.
when_to_use: |
  Examples that should trigger this skill:
    "research whether we should switch the default ORM"
    "investigate the SSR partial-nav approach and write it up"
    "evaluate Drizzle vs Prisma and record the decision"
    "spike path-alias imports and capture the findings"
    "this is a design record, where should it go"
    "write up the design for the streaming protocol"
  Use this the moment a task's deliverable is a writeup (a comparison, an options analysis, a design or decision record) with no code diff. The implementation that follows is separate tracked work filed via webjs-file-issue.
  Do NOT trigger for: filing an actionable feature/bug task (webjs-file-issue), starting work on an existing issue (webjs-start-work), or a change that ships a real code diff (that is a normal PR).
---

# Record a research / design investigation as a closed `research` issue

`agent-docs/` exists ONLY to teach AI agents how to USE webjs. It is NOT a home for research write-ups, design records, or decision histories. Polluting it rots its 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 under `agent-docs/`** (no `agent-docs/<topic>-design.md`, no `agent-docs/<topic>-research.md`). 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.

## 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 `agent-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 `agent-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

1. **Ensure the `research` label exists** (one-time):
   ```sh
   gh label list --repo webjsdev/webjs --search research
   # if absent:
   gh label create research --repo webjsdev/webjs --color 5319e7 \
     --description "Research/design/decision record (no code); filter these to read design history"
   ```
2. **Find or create the issue.** If a backlog `research` issue already exists for this question, use it. Otherwise create one:
   ```sh
   gh issue create --repo webjsdev/webjs --label research \
     --title "research: <question or decision>" --body-file <record.md>
   ```
   When appending to an existing backlog issue, also curate the final conclusion into its body so the answer is readable without the whole thread:
   ```sh
   gh issue edit <n> --repo webjsdev/webjs --body-file <updated-record.md>
   # confirm the label is present:
   gh issue edit <n> --repo webjsdev/webjs --add-label research
   ```
3. **Add deep-dive comments** for the threaded detail:
   ```sh
   gh issue comment <n> --repo webjsdev/webjs --body "## Deep-dive: ..."
   ```
4. **Close the issue as completed** (it is a record, not open work):
   ```sh
   gh issue close <n> --repo webjsdev/webjs --reason completed
   ```
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

```sh
# All research records, filterable by the label:
gh issue list --repo webjsdev/webjs --label research --state all
```