Code Research

Rank sources by authority. Higher tiers override lower tiers when they conflict.

Tier 1 — Standards and specifications

The ground truth. Always check here first when a standard exists.

Tier 2 — Big Tech engineering (on topics where they lead)

Trust a company's engineering publications only on topics where they are a recognized leader. A company's blog post outside their domain of expertise is Tier 5.

Tier 3 — Recognized expert figures

Individuals with sustained, peer-recognized contributions. Their writings carry authority on their specific domains.

Tier 4 — Well-maintained OSS projects

Reference implementations with strong governance. Code as documentation of best practice.

• Criteria: active maintenance, multiple contributors, clear governance, production use at scale
• Examples: React (UI), PostgreSQL (relational DB), Linux kernel (OS), Go standard library

Tier 5 — Community content

Useful for discovery and initial orientation. Never rely on as sole authority.

• Conference talks, blog posts, tutorials, Stack Overflow answers, Reddit discussions, dev.to articles, Medium posts
• Always verify claims from Tier 5 sources against higher-tier sources before adopting

2. Evaluating Sources

Recency

• Check version alignment: Is the advice for the current major version of the tool/language? Post-React 18 patterns differ significantly from pre-hooks era.
• Check standard status: Is the RFC ratified or still a draft? Draft standards may change. Note the distinction explicitly (e.g., "OAuth 2.1 draft" vs "RFC 9700").
• Deprecation signals: Archived repos, "this approach is no longer recommended" notices, superseded RFCs.

Context match

• Production scale vs hobby project: A pattern that works for a personal blog may fail at 10k RPS. Match the source's deployment context to yours.
• Team size: Patterns designed for 500-engineer organizations may have different trade-offs for a 3-person team — but smaller teams still need correct, robust implementations. Team size affects what you build, not how well you build it.
• Language/ecosystem: A pattern idiomatic in Go (explicit error returns) should not be cargo-culted into TypeScript (exceptions).

Conflict resolution

When authoritative sources disagree:

1. Trace to Tier 1: If a standard exists, it wins
2. Compare production evidence: Which approach is proven at scale? By how many independent organizations?
3. Check recency: The more recent source may reflect lessons learned
4. Note the conflict explicitly in findings — don't silently pick a winner
5. Present both positions with their trade-offs and let the planner/user decide

3. Research Process

Search strategy

Follow this order. Stop when you have sufficient authoritative coverage.

1. Official docs and specs — language reference, framework docs, relevant RFCs
2. Engineering blogs from domain leaders — Tier 2 companies on their specialty topics
3. Expert writings — Tier 3 figures on their domains
4. Reference implementations — Tier 4 OSS projects, read the actual code
5. Community content — Tier 5 for discovery, patterns you haven't considered

Cross-reference requirement

Before adopting a pattern or recommendation:

• Verify against at least two authoritative sources (Tier 1-3)
• If only Tier 5 sources exist, flag this explicitly in findings
• If a single authoritative source exists with no corroboration, note this — it may still be correct, but confidence is lower

Web search guidance

• Start with specific queries: "RFC 9457" problem details not api error handling
• Include version numbers: react 19 server components not react server components
• Prefer primary sources in results: site:datatracker.ietf.org, site:stripe.com/docs
• When evaluating blog posts, check the author's credentials and the publication date

4. Quality Standards

When researching implementations, evaluate every candidate pattern against these quality dimensions — in priority order:

Standards compliance

The best solution conforms to established standards. A technically elegant approach that violates HTTP semantics, language specifications, or protocol requirements is not a good solution. Standards exist because they encode hard-won consensus about interoperability and correctness.

Reliability and robustness

Prefer patterns that handle failure gracefully, degrade predictably, and have been battle-tested under adversarial conditions. Evaluate:

• Error handling completeness — does the pattern account for all failure modes, not just the happy path?
• Edge case behavior — how does it handle empty inputs, concurrent access, network partitions, clock skew?
• Recovery characteristics — does it fail fast, fail safe, or fail silently? Fail-fast with clear diagnostics is preferred.
• Observability — can you tell what went wrong from logs and metrics alone, without attaching a debugger?

Elegance and coherence

The best solution is the one that fully and properly solves the problem with nothing extraneous and nothing missing. Evaluate:

• Idiomatic to the language/framework — not translated from another ecosystem. Go error handling should not look like Java exceptions. TypeScript should use typed errors, not stringly-typed error codes.
• No unnecessary moving parts — fewer allocations, fewer indirections, fewer configuration knobs. But "fewer" never means "skip what's needed." Three lines of clear code beats a clever one-liner, but don't remove structure that protects correctness.
• Conceptual clarity — can a new team member understand the pattern without a 30-minute explanation? If not, the complexity must be justified by the problem's inherent complexity.
• Composability — does the pattern compose well with the rest of the system, or does it require special plumbing everywhere it's used?

Industrial-grade quality

The pattern should be production-ready — not a prototype that "works on my machine":

• Proven at scale — used in production by organizations that have validated the approach under load, failure, and maintenance pressure
• Maintainable — easy to modify, extend, and debug six months from now by someone who didn't write it
• Testable — can be unit tested, integration tested, and property tested without elaborate mocking
• Operationally sound — supports deployment, rollback, monitoring, and incident response

Language-specific idiom sources

Defer to the language-specific skill for detailed idiom guidance:

• TypeScript/React idioms → TypeScript skill (/typescript)
• For languages without a dedicated skill, refer to the language's official style guide and Tier 4 reference implementations

5. Reporting Findings

Attribution format

When writing research.md or reporting findings, attribute sources with:

• Tier level — so the reader knows the authority weight
• Author or organization — who said this
• Date or version — when, to assess recency
• URL — when available, for verification

Example: (Tier 1, IETF RFC 9457, 2023) or (Tier 2, Stripe engineering blog, 2024) or (Tier 5, Stack Overflow answer, 2022 — verify against primary source)

Confidence signals

• Flag when only lower-tier sources exist — "No Tier 1-3 sources found; recommendation is based on community consensus only"
• Flag conflicts explicitly — "Google AIP recommends X; Stripe practice differs with Y. Trade-off: ..."
• Flag draft standards — "Based on OAuth 2.1 draft (not yet ratified); may change"
• Flag recency concerns — "Source predates React 19; patterns may be outdated"

Structure

Write findings to research.md with sections: Summary, Stack, Existing patterns, Integration points, Gotchas, Testing, Open questions. Add a ## Sources section at the end with tiered attribution for all referenced materials.

6. Anti-patterns