Primary-Source Engineering Research

What it does

This compact skill delegates research to a fresh background agent so the main task can continue. Its substantive rule is source ownership: API behavior should be traced to official documentation, source code, specifications or first-party APIs rather than repeated from a secondary explanation. Findings are saved as one Markdown document following the project’s existing note convention. The source does not prescribe a vendor, paid search service or automatic truth score.

When to use it

• A migration depends on the exact behavior of an official SDK.
• An agent needs to compare documented retry and idempotency guarantees.
• A team wants a durable evidence note before choosing an implementation.

Step-by-step workflow

1. State the technical question, target versions and decisions the findings must support.
2. Give a fresh background research context pointers to the relevant project information.
3. Read the owning documentation, specifications and source for each material claim.
4. Write one Markdown note separating established facts, implications and unresolved questions with citations.
5. Return the note location and use its findings to inform the next decision.

Example request

Use research to establish the retry and idempotency behavior of the payment SDK version pinned in our lockfile. Read official API docs and relevant SDK source. Cite each claim about automatic retries, timeout handling and idempotency-key scope. Save one Markdown note beside our existing engineering research. Distinguish version-specific evidence from assumptions and list unresolved questions. Do not send real transactions, expose credentials or upgrade dependencies.

Worked example

A blog may say that failed requests are retried, but the owning SDK source may restrict retries to particular response codes. A useful note cites the applicable version and the exact condition, then explains what the application still needs to handle. If the documentation does not state whether a timeout can follow a successful charge, the researcher should preserve that uncertainty rather than promise safety. The note becomes a reusable input for design and tests, not a substitute for exercising the integration.

What you get

A single cited Markdown research document at the project’s established location, with unresolved questions kept visible.

How to evaluate the result

• Open citations and confirm each supports its associated claim.
• Check versions, publication dates and plan restrictions.
• Ensure missing evidence remains an open question instead of an invented conclusion.

What you need

Access to primary sources, a bounded question, version context and a writable notes location. The documented workflow uses a fresh background agent.

Setup and activation

The publisher documents plugin setup for Claude Code, Codex and Copilot, and manual Agent Skills setup for Gemini CLI and other clients. Choose one distribution method per client to avoid duplicate skills. The engineering collection expects project-specific tracker, triage-label and document-location settings from setup-matt-pocock-skills. Keep referenced companion skills and files available. This catalogue review does not install or run them; scan the exact source before any later installation. Client tools, permissions and subagent support still need separate validation.

Limits and considerations

Primary-source reading does not prove a deployed system behaves as documented. Documentation can drift, and claims may apply only to specific versions or plans. Citation presence alone does not establish that a source supports the sentence. Private files should not be uploaded to research providers without authorization.

Related workflows

• Use to-spec to translate researched constraints into a feature specification.
• Use diagnosing-bugs when the real system contradicts the documented behavior.

License and reuse

MIT at repository level (Copyright 2026 Matt Pocock). Preserve the copyright and permission notice when redistributing substantial source material; inspect any separately licensed dependencies or assets.

Further reading

• Publisher README: client setup and companion skills
• Reviewed SKILL.md (immutable commit)
• Reviewed MIT license