Source-Driven Development
Purpose
source-driven-development verifies technical correctness against authoritative
external sources. It prevents agents from implementing framework, library, API,
or platform patterns from stale memory.
This skill does not replace spec-driven-development. It verifies the
technical decisions inside a spec, plan, or implementation.
spec-driven-development = what we are building and why
source-driven-development = whether the technical pattern is correct today
When to Use
Use this workflow when any decision depends on external technical truth:
- Framework or library APIs, especially version-specific behavior.
- Runtime or platform constraints.
- Officially recommended patterns for routing, forms, auth, data fetching, state management, migrations, deployment, or testing.
- Deprecation, migration, or compatibility questions.
- User asks for "latest", "official", "best practice", "correct", "current", "documented", or "standards-compliant" implementation.
- A spec proposes a technical pattern that may conflict with current docs.
Do not use this workflow for pure product intent, copy changes, simple local logic, naming cleanup, or code whose correctness does not depend on an external versioned source.
Position in SDD
Use this as a verification layer:
New feature:
spec-driven-development -> source-driven-development if technical docs matter
-> planning-and-task-breakdown -> test-driven-development
Existing spec:
review-spec -> source-driven-development if technical docs matter
-> planning-and-task-breakdown
Implementation/review conflict:
source-driven-development finds docs/spec mismatch -> spec-evolution
If official sources contradict the approved spec, do not silently change the
spec or implementation. Route through spec-evolution and ask the user to
approve the updated path.
Source Hierarchy
Use the strongest available source for the specific decision:
| Priority | Source |
|---|---|
| 1 | Official framework, library, product, or API documentation |
| 2 | Official migration guides, release notes, changelogs, or RFCs |
| 3 | Official standards bodies or platform references such as MDN/web.dev |
| 4 | Runtime compatibility data from maintained compatibility references |
Do not use community posts, Stack Overflow, tutorials, AI summaries, or memory as primary evidence when official sources are available.
Workflow
1. Identify the Technical Decision
State the exact decision being verified:
Decision to verify: <framework/library/API pattern>
Why it matters: <risk if wrong>
Affected spec/plan/code: <file/section/task if known>
If there is no concrete technical decision, return to spec-driven-development,
review-spec, or planning-and-task-breakdown.
2. Detect Stack and Version
Read the smallest relevant files to identify versions and runtime context:
package.json, lockfiles,vite.config.*,next.config.*pyproject.toml,requirements.txt, framework settingsgo.mod,Cargo.toml,composer.json,Gemfile- existing source files that show local conventions
If the version cannot be determined and version affects the answer, ask the user
or mark the decision as UNVERIFIED.
3. Fetch or Locate Authoritative Sources
Use official docs for the specific feature, not a broad homepage. Prefer deep links to the page or section that supports the decision.
Capture:
- Source URL or local official doc path.
- Version or date if visible.
- The specific rule, API, constraint, or deprecation relevant to the decision.
- Any ambiguity or missing official guidance.
4. Compare Docs to the Spec, Plan, and Code
Classify the result:
CONFIRMED: official sources support the proposed pattern.ADJUST: official sources support a different pattern; update proposal viaspec-evolutionif the spec was already approved.CONFLICT: official sources and existing codebase conventions disagree; present options and ask.UNVERIFIED: no authoritative source was found or version is unknown.
Do not overrule local architecture automatically. If current docs and existing code disagree, surface the tradeoff:
Option A: follow current official docs
Option B: match existing project convention
Option C: adapt via a compatibility wrapper
5. Record the Evidence
For any non-obvious decision, include the evidence in the spec, plan, review, or final response:
## Source Verification
**Decision:** [technical pattern]
**Stack/version:** [detected version or unknown]
**Sources:** [official URLs or local docs]
**Result:** CONFIRMED | ADJUST | CONFLICT | UNVERIFIED
**Impact:** [spec/plan/code consequence]
If the discovery reveals a durable caveat, use annotate to persist it.
Anti-Rationalizations
| Thought | Required correction |
|---|---|
| "I know this API." | Memory is not evidence. Verify version-sensitive patterns. |
| "The docs will take too long." | A wrong framework pattern costs more than a targeted docs check. |
| "The spec already says what to use." | Specs can be technically stale; verify external truth when it matters. |
| "A popular blog says this is best practice." | Use official sources first. Blogs can inform, not authorize. |
| "The docs conflict with our code; I'll just pick one." | Present the conflict and route through spec-evolution if approved scope changes. |
| "I could not verify it, but it is probably fine." | Mark it UNVERIFIED and narrow the claim. |
Stop Conditions
Stop and ask before proceeding when:
- Required docs are inaccessible and the decision is high risk.
- Framework version is unknown and changes the implementation pattern.
- Official guidance contradicts an approved spec.
- The documented pattern requires a dependency, migration, security exception, or architecture change not already approved.
Integration
using-sddroutes version-sensitive technical decisions here.spec-driven-developmentdefines the product and technical intent; this skill validates external technical correctness.review-speccan call this when spec readiness depends on official docs.planning-and-task-breakdownshould carry source verification notes into task acceptance criteria.spec-evolutionhandles approved spec changes caused by source findings.