Source Driven Development

Source-Driven Development

You implement framework-specific code from official documentation for the detected version, not from training-data memory. Every non-trivial framework decision is cited or flagged unverified.

Hard Rules

Read dependency manifests (package.json, pyproject.toml, go.mod, etc.) before writing framework-specific code. Fetch the specific doc page for the feature — not the framework homepage. Never cite Stack Overflow, random blogs, or training data as primary authority. If versions are ambiguous, ask once — do not guess. Surface conflicts between docs and existing codebase; do not silently pick one. Mark patterns you could not verify as UNVERIFIED explicitly.

Workflow

Step 1 — Detect stack and versions

Read the project's dependency file. State findings explicitly:

STACK DETECTED:
- [package] [version] (from [file])
→ Fetching official docs for [feature].

If versions are missing, ask the user before implementing.

Step 2 — Fetch official documentation

Fetch the relevant documentation page for the exact API or pattern. Use references/source-hierarchy.md. Prefer hooks/sdd-cache (Claude Code) or python3 .agents/skills/research-skill/scripts/doc_cache.py "<url>" — see research-skill → references/doc-cache.md.

Extract: API signatures, recommended patterns, deprecations, migration notes. If official sources conflict, surface the discrepancy to the user.

Step 3 — Implement documented patterns

• Use signatures and patterns from the fetched docs.
• Prefer current recommended APIs over deprecated ones from memory.
• When docs conflict with existing project code, present options A/B and wait for preference.

Step 4 — Cite sources

In code (framework-specific lines only):

// useActionState for form pending state — React 19
// Source: https://react.dev/reference/react/useActionState#usage

In chat: full URLs, quote non-obvious passages, note browser/runtime support when relevant.

If no official doc exists for a pattern:

UNVERIFIED: No official documentation found. Based on training data — verify before production.

When NOT to use

• Renames, typos, file moves with no API surface change
• Pure language logic identical across versions
• User explicitly wants speed over verification ("just do it quickly")

Gotchas

• Training data lags; "confident" APIs are often deprecated.
• Fetching the whole docs site wastes tokens — one page per decision.
• Simple snippets become copy-paste templates — wrong patterns spread fast.
• Version skew: React 18 patterns in a React 19 repo break silently.

Common Rationalizations

Output Format

## Source-driven — [feature/slug]

Stack: [detected versions]
Docs fetched: [URLs]
Implementation: [summary]
Citations: [list or UNVERIFIED items]
Conflicts with codebase: [none | options A/B]

Examples

Verification

• Versions read from dependency file (or user confirmed)
• Official docs fetched for each framework-specific pattern used
• Code matches current-version documented APIs (no deprecated APIs without flag)
• Non-trivial decisions have full URL citations or UNVERIFIED labels
• Doc vs codebase conflicts surfaced to user

Red Flags

• API choice made from training data not fetched docs
• Entire docs site fetched instead of one decision page
• Deprecated API used because snippet was memorable
• Version in code mismatches version cited from docs

Reference Files

• references/source-hierarchy.md: Authority order and non-authoritative sources — read at Step 2.

Prune Log

Last pruned: 2026-07-04

• No changes — citation audit passed; content current (improve-skills full pass 2026-07-04)

Impact Report

Feature: [slug] | Stack: [versions]
Docs: [count] fetched | UNVERIFIED: [count]
Conflicts surfaced: [yes/no]