Research

Answer the question, then file the answer where someone will find it next time.

Most research docs are written once and never opened again. In one shipped app, 108 of 134 research docs were never touched after the day they were written. What got read was the one line summary in the rules file's Docs index, because the rules file is loaded every session. So the index line matters more than the doc. Write both, and write the index line as if it is the only thing anyone will read.

Do not write app code during research. If the answer says to change something, say so and let the user decide.

1. Pin down the question

Restate the question in one sentence, and the decision it should inform. If the question is too vague to answer (for example "look into payments"), ask one short question to narrow it. Otherwise start.

2. Look at what the project already knows

Before searching the web:

1. Read the Docs section of the rules file (CLAUDE.md or AGENTS.md).
2. Search the docs folder and the root docs for the topic and its synonyms: grep -ril "<term>" docs/ *.md. Try two or three words, not one.
3. Search the code for the feature or library involved.

If an existing doc already answers the question and its date is recent enough for the topic, answer from it, cite it, and stop. Say how old it is. Store rules, prices and library versions go stale in months; product reasoning lasts longer.

3. Research

Sources, in this order of trust:

1. Official docs for the thing in question (the store, the platform, the library's own docs and changelog, the vendor's pricing page).
2. Primary sources: the library's source code or issue tracker, a release note, a test you run yourself.
3. Secondary sources: blog posts, forum answers, videos, other people's skills and repos. Treat these as leads to check, not as answers.

Rules:

• Cite every claim that matters with a link and the date you read it.
• If a claim comes only from a secondary source, or from memory, mark it (unverified) and say what would confirm it.
• Prefer concrete numbers: limits, prices, sizes, timings, version numbers.
• When sources disagree, say so and say which one you trust and why.
• Prefer depth on the two or three real options over a long shallow list.
• For store rules or console steps, read the current official page now. Never state them from memory.

4. Decide where it goes

File into an existing doc whenever one fits. Create a new doc only when nothing does. Check in this order:

1. An existing doc on the same topic found in step 2. Add a dated section, or update the old one and note what changed and when. Do not leave two answers that disagree.
2. A doc the answer naturally belongs in: the backlog item it informs (add research notes to that item), the algorithms doc for logic, the rules file's Standing decisions if the user makes a decision from it, the rules file's Gotchas if it explains a surprise that cost time.
3. A new doc, only if nothing above fits. Use templates/research-doc.md from this skill's folder. Put it in docs/research/ with a plain topic name, for example docs/research/push-notification-providers.md.

Never create an archive folder. Git keeps history.

5. Write the entry

Whether it is a new doc or a section in an old one, every entry has:

• A date (YYYY-MM-DD) on the entry itself, not just the file.
• The question, in one sentence.
• The answer first: the finding and the recommendation, in two or three lines.
• The detail: options, numbers, trade offs, rough effort (small, medium, large).
• Sources, official first, each with a link and the date read.
• Unverified: anything not confirmed, listed plainly with what would confirm it.
• Open questions: what is still unknown and who could answer it.

Keep it as short as the answer allows. A long doc nobody reads helps nobody.

6. Update the Docs index

In the rules file's Docs section, add or update one line for the doc:

- `docs/research/push-notification-providers.md`: Provider A is cheapest under 10k
  users and has an Expo plugin; Provider B only wins on rich media (2026-10-11)

The line must carry the headline finding, not just the topic. "Research on push providers" is useless; the reader still has to open the file. Include the key number or the recommendation and the date. If the doc already has a line, rewrite it so it matches the newest finding.

If the entry went into a doc that is already indexed (the backlog, the algorithms doc), update that doc's line only if its headline changed.

If the rules file has no Docs section, add one at the end with the heading ## Docs and the sentence "One line per doc, with its headline number, so the summary is enough most of the time."

7. Answer in chat

Lead with the answer:

1. The short answer and recommendation, in two to four lines.
2. Anything unverified, in one line.
3. Where it was filed: the doc path, and that the Docs index line was added or updated.

Do not paste the whole write up into chat. If the user wants the detail, it is in the doc.

Do not

• Do not create a new doc when an existing one covers the topic.
• Do not leave an entry without a date or without sources.
• Do not present a blog post, a forum answer or memory as confirmed.
• Do not leave the Docs index line as a bare title.
• Do not commit. The session end skill, or the user, does that.