research-systematically

Research Systematically

Turn an uncertain question into a reproducible research record without presenting exploration as confirmation, and ground every external-API claim in current, version-matched documentation instead of recollection.

Keep a research record

Maintain one plain file (markdown or JSON, in a scratch directory or outside the repo) holding: the research question, the frozen plan, an evidence log, dead ends, pivots, and the final verdict. Append to the evidence log; never rewrite or delete earlier entries. The pre-registration section is written once and left untouched after results exist.

1. Freeze the question

Before collecting any result evidence, write down:

• The question, stated once.
• Hypotheses, each with a concrete prediction and a falsifier — what observation would prove it wrong.
• Methods and planned experiments, each with a stable ID.
• Stopping rules: what ends the research besides an answer.

Do not edit this section after results are known. Record deviations, failed approaches, and pivots as new entries instead of rewriting the original plan.

2. Establish local versions before consulting docs

When the research or implementation touches an external library, framework, SDK, CLI, or cloud API:

• Inspect the manifest or lockfile first. The repository, not memory, says which release is installed.
• Never guess a version the repository can provide.
• Local code, callers, and tests stay authoritative for project behavior; external docs describe the external contract only.

3. Retrieve version-matched documentation

Prefer freshness over recollection: an API surface that may have drifted is confirmed against a current source, not recalled.

• If a documentation-lookup MCP tool (such as Context7) is available: resolve the library ID, pick the closest name with suitable coverage and reputation, prefer an ID matching the locally installed version, and query one concrete topic.
• Otherwise use the vendor's authoritative documentation directly and note which channel was used.
• At most three documentation queries per task. Split unrelated topics into separate queries.
• Never send credentials, private source, customer data, or complete error dumps in a query.
• For each lookup, log: library, version matched, exact query or topic, source URL, and retrieval date. Treat a lookup as stale once the installed dependency version changes or the entry is older than about a day — re-retrieve rather than reuse.