Research Methodology

When to apply

Apply whenever the task requires investigation before action: unfamiliar APIs, stack selection, implementation planning, code review, architecture decisions, or root-cause analysis of regressions.

Research is ~70–80% of software work. Code is the expression of research conclusions, not a substitute for it.

Research progress checklist

Copy this checklist into your first reply and update it as you go. A step counts as done only when its written output appears in the conversation or in the deliverable.

Research progress:
- [ ] 1 Canon: ranked source list written
- [ ] 2 Charter: goal, scope/object/subject, type + why, questions, reachable sources
- [ ] 3 Type file read (research-<type>.md); findings ledger kept while collecting
- [ ] 4 Scope filter: what was discarded/revised (or "nothing, because ...")
- [ ] 5 Object filter: what was discarded/revised (or "nothing, because ...")
- [ ] 6 Conclusions: each backed by a ledger row; open questions listed as risks

Gate rule: do not collect data (tool calls, file reads, web lookups, or reasoning from memory) before steps 1 and 2 are posted. Do not write conclusions before steps 4 and 5 are posted. Every task gets a charter; only its length varies (see Step 2).

Gating questions

Before any research, answer explicitly:

1. Goal — What verifiable outcome must this research produce?
2. Knowledge depth — How well do I already understand the object? (none / surface / working / deep)

No goal → research never completes correctly. Wrong self-assessment → wrong research type.

Three levels (define in the charter)

Chain: Scope → Object → Subject (general → specific). Subject-level conclusions must stay consistent with object and scope context. Adjacent subjects must not contradict each other relative to the larger levels.

Concrete examples:

"Information technology → software development → a library" is too abstract to guide a filter. If your levels read like that, narrow them until each one names something you could point at.

Research type selection

Rules:

• Exploratory + descriptive = theoretical (understand future application; no working artifact required).
• Experimental = practical (learn from historical/recorded data of a working system).
• Never use experimental when the object is not yet understood; conclusions will be wrong at a fundamental level.
• Poor exploratory work surfaces as surprises during descriptive work. Good exploratory work makes descriptive work precise.

Typical chaining: Exploratory (pick stack) → Descriptive (spec per milestone) → Experimental (root-cause after shipping).

Research pyramid — execute in order

Step 1 — Establish canon

Identify sources closest to truth. Rank every source you intend to use:

On doc/code conflict: resolve via author intent, never by preference.

If the subject is a third-party library, framework, or platform, at least one rank 1–2 source is mandatory. Reading only the local copy of its code is not enough to establish canon.

If a source class is unreachable in the current environment (no web access, no repository, no docs tool), write unavailable next to it in the charter. Conclusions that would depend on it are reported as unverified, not as facts.

Output: the ranked list, posted before collection starts.

Step 2 — Define interpretation rules (the charter)

Post the charter as a message before the first data-collection action. Format:

Charter
- Goal: <verifiable outcome>
- Scope / Object / Subject: <...> / <...> / <...>
- Type: <exploratory | descriptive | experimental> — because <one sentence>
- Questions: Q1 <...>; Q2 <...>; ...
- Sources: <ranked list from Step 1, with `unavailable` marks>

Length rule:

• Small task (single subject, expected ≤5 sources, no third-party unknowns): the five lines above are the whole charter. Still post them.
• Anything else: full charter, and each question gets its own line so the ledger can reference it.

Most common failure: treating personal knowledge as canon and skipping this step. A charter written after collection is not a charter; it is a rationalization.

Step 3 — Execute research and record findings

1. Read the detail file for the chosen type with your file-reading tool: research-exploratory.md, research-descriptive.md, or research-experimental.md. An inlined SKILL.md does not include them. If files cannot be read in the current environment, say so and follow the type's steps as summarized in the selection table.
2. Keep a findings ledger and append to it after every batch of reads, lookups, or observations. One row per claim:

| # | Claim | Evidence (file:line / URL / version / commit) | Rank | Answers |
|---|-------|-----------------------------------------------|------|---------|
| F1 | Plugin rejects ids > Int.MAX_VALUE | LocalNotification.kt:131, @capacitor/local-notifications 8.3.1 | 3 | Q1 |
| F2 | Maintainers require signed 32-bit ids | CHANGELOG 8.0.0 "breaking: ids must be int32" | 1 | Q1 |

A finding without evidence is a hypothesis; put it in a separate Open list, not in the ledger. Re-reading a source you already have a ledger row for is a signal that the ledger is incomplete: fix the row, do not re-read. 3. Stop collecting when every charter question has at least one rank 1–3 row, or is explicitly marked unanswered. Unanswered questions go to Step 6 as risks, never as guesses.

Output: the ledger (table) plus the Open list. No conclusions yet.

Step 4 — Filter by scope context

Review every ledger row against the scope. Discard or revise rows that ignore domain constraints, history, or cross-cutting principles valid at this level.

Ask: "Does this hold within the broader domain, not just in this narrow case?"

Output, always posted even when nothing changes:

Scope filter: discarded F<...> because <...>; revised F<...> to <...>.

or

Scope filter: nothing discarded — <one sentence why the rows already respect the domain>.

Step 5 — Filter by object context

Review surviving rows against the object. Discard or revise rows distorted by imperfect research conditions or over-generalized from the subject.

Ask: "Does this apply to the target system/component, not just the specific artifact I studied?"

Output, same format as Step 4, always posted.

Step 6 — Formalize and apply

Produce final, verifiable conclusions. Every conclusion cites the ledger rows it rests on. Every unanswered charter question appears as a risk with a proposed way to close it.

The deliverable must contain these sections in this order, regardless of where it lives (chat reply, plan document, spec file, issue comment):

## Charter
## Canonical sources
## Findings ledger
## Scope filter
## Object filter
## Conclusions            <- each item: statement + ledger refs
## Next steps / Risks     <- or Implementation steps + Acceptance criteria for a plan

When the deliverable is an implementation plan (for example a plan-mode document), the research sections above go first, then the implementation steps. Use the output template of the chosen type file for the type-specific content (comparison table, acceptance criteria, classification table).

Anti-patterns

Research exists to produce repeatable, checkable outcomes, not activity for its own sake.