dev-research-adaptive

name	dev-research-adaptive
short_description	Adaptive development research for agents that are stuck, uncertain, or need industry/open-source prior art before deciding or coding.
description	Use this skill when a development agent needs external research, prior art, open-source examples, official documentation, architecture alternatives, debugging clues, dependency evaluation, or a fresh angle after an idea crisis. Adapts depth from quick scout for drafts/spikes to deep evidence review for architecture, security, data, migrations, public APIs, dependency adoption, and production-critical decisions. Do not use for simple local edits that can be solved from the repository context alone.

Dev Research Adaptive

This skill turns “I’m stuck” into a disciplined but right-sized research workflow. It is for agents that need to look outside their current reasoning loop: official docs, source code, issue threads, RFCs, ADRs, design docs, open-source implementations, changelogs, benchmarks, and postmortems.

The goal is not to produce a long literature review. The goal is to find useful evidence, extract patterns, make trade-offs explicit, and return a decision or next experiment that fits the user’s actual task.

When to use this skill

Use this skill when the task contains signals like:

• “I’m stuck”, “no ideas”, “look at it from another angle”, “find prior art”, “how do others do this?”
• “research”, “investigate”, “compare approaches”, “industry practice”, “open-source examples”.
• Unknown library/framework behavior, migration strategy, API design, architecture decision, performance issue, security concern, or dependency adoption.
• A feature or bug has multiple plausible implementations and local context is not enough to choose.
• The user asks for a spike, draft, prototype, or quick hypothesis and wants just enough research to move.
• Another skill cannot proceed confidently and needs external evidence.

Do not use this skill when:

• The answer is fully determined by local code/spec and no external or cross-project evidence is needed.
• The user explicitly says not to browse/search/research.
• The task is a pure rewrite, formatting, or mechanical code edit.
• Using external search would expose secrets or proprietary code. Sanitize queries first.

Core principle: adaptive research depth

Choose the minimum useful research depth. Quick work should stay quick. Risky or durable decisions require evidence.

Mode	Use for	Required rigor	Output shape
R0 — Local reframing	Agent is stuck but likely has enough local context	Reframe assumptions, inspect local docs/code, no external search unless needed	Short options + next experiment
R1 — Quick scout	Drafts, spikes, prototypes, hypothesis checks	2–5 useful sources; at least one primary source for technical facts when available	Short finding + links/evidence + caveats
R2 — Standard dev research	Normal implementation choice or debugging unknown behavior	Official docs + open-source/code examples + one contrary/alternative search	Structured brief + recommendation
R3 — Deep prior-art review	Architecture, cross-team, public API, scaling, dependency choice, major refactor	Source matrix, alternatives, version check, OSS implementation review, risks, ADR/RFC-ready summary	Research memo or ADR/RFC draft
R4 — Critical evidence gate	Security, auth, PII, data loss, migrations, payments, compliance, destructive ops	Primary sources/advisories/specs only for core claims; explicit uncertainty; no shortcuts	Risk memo + approval/verification gates

Escalate depth when any of these are true

• The decision affects auth, authorization, tenant isolation, secrets, PII, payments, billing, credits, quotas, migrations, backfills, destructive operations, public APIs, SDKs, data retention, or production deploy behavior.
• The user asks for “best”, “safe”, “production-ready”, “industry standard”, or “how mature projects do it”.
• The result may introduce a new dependency or remove/replace a major subsystem.
• Sources disagree, are stale, target different versions, or only show toy examples.
• A previous implementation attempt failed and the failure mode is not understood.

De-escalate depth when any of these are true

• The user explicitly says “draft”, “spike”, “quick mock”, “prototype”, “just check the idea”, or “not production”.
• The output will not be merged, deployed, persisted, or used for user/security/data decisions.
• The research question can be answered by one official doc page plus one example.

Even in R1, be honest: label fake data, missing tests, unverified assumptions, and production hardening steps.

Required workflow

1. Frame the research question

Before searching, write the research target internally:

• Decision to make: what choice must this research enable?
• Current local context: stack, versions, constraints, existing architecture, relevant files.
• Risk flags: security, data, migration, reliability, performance, public API, dependency adoption.
• Desired output: quick answer, recommendation, implementation plan, ADR/RFC, or risk memo.
• Stop condition: what evidence is enough for this mode?

Ask at most one clarifying question only if the missing detail blocks useful research. Otherwise state assumptions and proceed.

2. Inspect local context first when available

Do not research generically if the repository or spec is available. Inspect relevant local materials first:

• README, architecture docs, ADR/RFC/design docs, product spec, issue/PR description.
• Package manifests, lockfiles, framework versions, runtime versions.
• Existing APIs, data models, migrations, queues, background jobs, auth boundaries.
• Tests, fixtures, error logs, failing stack traces, telemetry names, feature flags.
• Internal conventions: naming, layering, validation, error handling, observability, rollout.

Use scripts/extract_repo_research_context.py when a quick local inventory would help.

3. Build a search plan with lanes

For R1, use only the lanes needed. For R2+, cover at least three lanes:

1. Primary documentation lane

   • Official docs, API references, changelogs, release notes, migration guides, standards, security advisories.
   • Always check version compatibility with the project.

2. Open-source implementation lane

   • Mature repositories, official examples, tests, adapters, plugins, templates, real configs.
   • Inspect source code and tests, not just README snippets.

3. Design/industry lane

   • ADRs, RFCs, design docs, accepted proposals, engineering blogs from reputable teams, postmortems, benchmark write-ups.
   • Extract trade-offs, not slogans.

4. Negative/contrary lane

   • Search for “why not”, “pitfall”, “migration issue”, “security advisory”, “bug”, “performance”, “deprecated”, “breaking change”.
   • Look for rejected alternatives and failure modes.

5. Adjacent-domain lane

   • When the model has an idea crisis, search adjacent ecosystems or older battle-tested systems with similar constraints.
   • Example: queue retry design can learn from payments/webhooks/email delivery; state machine design can learn from workflow engines.

4. Evaluate source quality

Use references/source-quality.md.

Default trust order:

1. Official docs, standards, release notes, specifications, security advisories.
2. Source code and tests from official or mature projects.
3. Maintainer issue/PR discussions and accepted RFCs/ADRs/KEPs.
4. Reputable engineering blogs with concrete context and dates.
5. Stack Overflow, tutorials, gists, snippets, newsletters, and SEO blogs as clues only.

For open-source repositories, check:

• License compatibility.
• Latest release and recent maintenance.
• Issue/PR health and maintainer involvement.
• Tests/CI/security policy when relevant.
• Whether the example is a toy, benchmark, template, or real production-shaped implementation.

Do not treat stars as proof of correctness.

5. Extract patterns, not copy-paste

When inspecting examples, extract:

• The problem shape and constraints.
• The data model or API boundary.
• Error handling and failure behavior.
• Idempotency/retry/concurrency assumptions.
• Rollout/migration strategy.
• Testing strategy.
• Observability hooks.
• Trade-offs and what the project explicitly avoids.

Never copy significant code from third-party projects into the user’s codebase unless the user explicitly asks and license compatibility is checked. Short snippets for explanation are okay when allowed by the environment.

6. Synthesize into a decision

Do not dump links. Produce a synthesis:

• What the sources agree on.
• What they disagree on.
• What applies to this project and what does not.
• Options considered.
• Recommendation.
• Minimal next experiment or implementation path.
• Verification plan.
• Caveats and confidence.

For R2+, include at least one rejected alternative and why it is rejected.

7. Handoff to implementation or planning

Research should end in an actionable handoff:

• For a spike: “try this next” with a tiny validation step.
• For implementation: concrete files/components/modules likely affected and tests to add.
• For architecture: ADR/RFC-ready summary with context, decision, alternatives, consequences.
• For review: risks to check and evidence needed before approving.
• For dependency adoption: license/security/maintenance checklist and integration risk.

If another skill should take over, say so explicitly: backend developer, frontend developer, review, QA, migration, security, or planning.

Search tactics

Use references/query-cookbook.md for detailed query patterns.

Good searches are scoped and adversarial:

• Exact error strings in quotes.
• Library + version + API/feature name.
• Official docs + migration guide + changelog.
• site:github.com with path/file hints.
• GitHub code search with repo:, org:, language:, path:, symbol:, quoted strings, boolean operators, and regex.
• Sourcegraph with repo/language/file filters for broad OSS patterns.
• “pitfall”, “deprecated”, “breaking change”, “security advisory”, “CVE”, “regression”, “why not”, “alternatives”.

Avoid these searches as primary evidence:

• “best way to do X” without version or stack.
• Broad SEO queries that return generic tutorials.
• Single blog post confirmation searches.
• Searching only for the answer you already want.

Anti-patterns

Avoid:

• Research theater: long lists of sources with no decision.
• Cargo-culting: copying a big-tech/open-source pattern without checking constraints.
• Source laundering: citing a blog that merely repeats official docs instead of citing the docs.
• Version blindness: applying examples from old major versions to current code.
• Toy-example bias: treating tutorial code as production design.
• Star-count fallacy: assuming popular means correct, maintained, secure, or appropriate.
• Confirmation search: searching only for sources that support the first idea.
• Over-researching drafts: turning a quick spike into a thesis.
• Under-researching risk: treating auth/data/security/migrations as a quick guess.
• Unlicensed copying: pasting meaningful third-party code without license review.
• Secret leakage: searching exact proprietary identifiers, customer data, tokens, or internal URLs.

Quality gates

Before returning, check:

1. Fit gate — Did the research answer the actual decision/problem?
2. Depth gate — Did the depth match risk and user intent?
3. Source gate — Are core claims backed by primary or high-quality sources?
4. Freshness gate — Are versions/dates compatible with the project?
5. OSS gate — Did open-source examples include source/tests/config, not just README text?
6. Contrary gate — Did R2+ include at least one pitfall, rejection, or alternative?
7. Actionability gate — Is there a next step, implementation path, or decision?
8. Caveat gate — Are uncertainty, assumptions, and non-production shortcuts visible?
9. Safety gate — No secrets leaked; high-risk recommendations have verification/approval notes.

Output formats

R0/R1 quick scout

Mode: R1 — Quick scout

Problem / decision:
Assumptions:

Finding:
- ...

Evidence:
- [source] — what it proves / why it matters
- [source] — what it proves / why it matters

Recommendation:

Try next:

Caveats / confidence:

R2 standard research brief

# Dev research brief: <topic>

Mode: R2 — Standard dev research

## Decision to make

## Local context inspected

## Sources inspected
| Source | Type | Version/date | Useful evidence | Caveat |
|---|---|---:|---|---|

## Patterns found

## Options
| Option | Pros | Cons | Fits our project? |
|---|---|---|---|

## Recommendation

## Implementation implications

## Verification plan

## Open questions / caveats

R3/R4 deep memo or ADR-ready output

# Research memo / ADR draft: <decision>

## Status
Proposed / needs approval / blocked pending evidence

## Context

## Decision drivers

## Evidence summary

## Source matrix
| Claim | Evidence | Source quality | Version/date | Confidence | Caveat |
|---|---|---|---:|---|---|

## Options considered

## Recommended decision

## Consequences

## Rollout / migration / verification

## Risks and mitigations

## What would change my mind

## Appendix: sources inspected

Hard rules

• Do not fabricate research, sources, quotes, commit behavior, package health, or industry consensus.
• Do not claim “industry standard” unless supported by a standard, official docs, or multiple independent mature examples.
• Do not use community snippets as the only evidence for security, auth, data, or production migration decisions.
• Do not paste secrets or proprietary code into external search queries. Sanitize identifiers and customer data.
• Do not copy third-party implementation code unless explicitly requested and license compatibility is checked.
• Do not overbuild the output for drafts/spikes. Keep quick research quick.
• Do not under-research high-risk decisions. Escalate to R3/R4 when risk flags appear.
• When citations are available in the environment, cite all internet-derived factual claims.
• When sources conflict, show the conflict instead of hiding it.
• If research access is unavailable, say so and use local docs/code only; do not pretend external research happened.

Examples

Quick prototype

User: “I need a quick way to mock webhook retries for a frontend demo.”

Use R1. Search official webhook retry docs only if needed, inspect one mature example, return a minimal local-only approach and hardening checklist.

Production webhook design

User: “Design invoice.paid webhook handling for production billing.”

Use R3/R4. Research provider docs, signature verification, idempotency, retry behavior, event ordering, OSS examples, and failure modes. Return ADR-ready recommendation and verification gates.

Idea crisis

User: “The agent keeps proposing the same notification architecture. Find another angle.”

Use R2. Reframe using adjacent domains: email delivery, incident alerting, activity feeds, workflow engines. Extract patterns and propose 2–3 alternatives.

Dependency adoption

User: “Should we add library X?”

Use R2 or R3 depending on criticality. Check official docs, release cadence, issues, security posture, license, alternatives, integration surface, migration/exit cost, and project fit.