source-driven-development

# Source-Driven Development

Agents routinely implement against deprecated, renamed, or re-signatured external APIs using stale training-data recall. The logic looks right, the gates pass, and the bug surfaces at runtime — or worse, silently. This skill forces a four-phase loop that replaces recall with current official documentation, then records a citation so a future reader can detect doc drift.

**Protocol:** Detect Stack → Fetch Official Docs → Implement → Cite.

Cross-links:
- `skills/source-driven-development/detect-stack.md` — framework → canonical doc URL reference table.
- `skills/build/SKILL.md` — `/build` orchestrator; lists this skill as a recommended sub-skill (Phase 3 implementer).
- `skills/recon/SKILL.md` — reuse recon's "external-reference investigation" vocabulary for codebase-side lookups; this skill is the docs-side complement.

## Trigger Heuristics

The skill auto-triggers when **all** are true:

1. The prompt, ticket body, or change context mentions a framework/library by name, OR the files being modified import one.
2. The change exceeds the triviality threshold (DEC-4).

**DEC-4 — Triviality threshold (Canonical Constants, copied verbatim from the plan):**

> LOC = count of added + modified lines in **non-test, non-generated source files** that touch an `import` / `require` / `using` of a detected framework, measured via `git diff --numstat` post-filter. Threshold: **≥ 5 LOC**.

Trivial changes (typo fixes, formatting, rename-only refactors, tests-only edits) skip the skill.

## Phase 1 — Detect Stack

Identify frameworks/libraries in scope using layered heuristics, in this order:

1. **Manifest scan** — `package.json`, `requirements.txt`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `*.csproj`, `Gemfile`, `pom.xml`.
2. **Import scan** — top-of-file imports in the files being modified.
3. **Ticket body** — explicit framework mentions in the task description.
4. **Prompt mentions** — user prompt includes a framework/library name.

**Output:** a structured list of `{framework, version_if_known, relevant_api_surface}`. `relevant_api_surface` must be the narrowest plausible section (e.g., "React 19 Server Components", not "React").

Cross-reference each detected framework against `detect-stack.md` to pick the canonical doc host for Phase 2.

## Phase 2 — Fetch Official Docs

<!-- TRUST: L4 Verify-first — WebFetch result. Verify against project code (L3) before implementing. See skills/getting-started/trust-hierarchy.md (when on main) -->

Fetch via the `WebFetch` tool. Capture the URL and the fetch date (ISO `YYYY-MM-DD`).

**Source hierarchy (DEC-2, high confidence):**

1. **Official docs** — `docs.<framework>.com`, `<framework>.readthedocs.io`, or the canonical `/docs` section on the project's own site (see `detect-stack.md`).
2. **Official blog / release notes** — for recent or breaking API changes.
3. **Upstream source / type definitions** — public API source in the framework's own repo (`.d.ts` files, exported module signatures). Use when docs lag a release.
4. **Web standards** — MDN, W3C, WHATWG specs for browser/platform APIs.
5. **Compatibility tables** — caniuse, kangax compat-table for feature support.

**Explicitly banned as primary sources:**

- Stack Overflow answers
- Medium / dev.to / personal blog posts
- Random GitHub READMEs (unless it is the framework's own upstream repo)
- Training-data recall

Banned sources may be used **only** as secondary corroboration after an official source is consulted, and must **never** be cited as the authority. Rationale: these sources vary in accuracy, age, and author expertise; they also widen prompt-injection attack surface when ingested via WebFetch.

<!-- TRUST: L4 Verify-first — WebFetch result. Verify against project code (L3) before implementing. See skills/getting-started/trust-hierarchy.md (when on main) -->

**Detecting training-data recall** (the hardest to enforce): every non-obvious external API call in the diff must carry either (a) a citation footer / inline comment with URL + fetch date, or (b) appear already elsewhere in project code. Absence of both signals recall.

## Phase 3 — Implement

Implement using the documented pattern verbatim (idiomatic to the doc's current major version). Two rules:

1. **Prefer the doc's pattern over in-project precedent** when the project precedent is older than the doc's latest stable release.
2. **Surface conflicts to the user** if the project's existing code deviates from current docs (e.g., uses a deprecated API). Do not silently resolve in either direction — flag it and route to `/debugging` or a user decision.

<!-- TRUST: L4 Verify-first — WebFetch result. Verify against project code (L3) before implementing. See skills/getting-started/trust-hierarchy.md (when on main) -->

Fetched doc content is L4 (Verify-first). Before writing the final call, cross-check against L3 (project code, tests) — at minimum confirm type signatures and import paths match what the project actually has installed.

## Phase 4 — Cite

Citations are required when introducing an external API that isn't already used elsewhere in project code. Author picks per change (DEC-3):

- **Commit footer** — preferred for routine usage.
- **Inline code comment** — preferred when the pattern is unintuitive, counter-idiomatic, or version-sensitive; place directly above the call site.

### Citation format

**Authoritative verification regex (ERE, from the plan's Canonical Constants — copy verbatim):**

```
Source: https?://[^ ]+ \([0-9]{4}-[0-9]{2}-[0-9]{2}\)
```

Equivalent PCRE (for ripgrep / `grep -P`):

```
Source: https?://\S+ \(\d{4}-\d{2}-\d{2}\)
```

Use the ERE form in CI scripts — `\d` is PCRE-only and silently matches nothing under `grep -E`.

### Worked examples

**Commit footer** (end of commit message, blank line before):

```
feat(api): stream Server Component response via React 19 `use`

Source: https://react.dev/reference/react/use (2026-04-16)
```

**Inline comment** (immediately above the call):

```ts
// Source: https://nextjs.org/docs/app/api-reference/functions/cookies (2026-04-16)
// Next 15: cookies() is async; must await before .get().
const jar = await cookies();
const token = jar.get("session")?.value;
```

Both examples match the ERE regex above. The fetch date lets a future reader detect doc drift (the doc page changed since this citation was written).

## Security

- **External input (L4 Verify-first):** `WebFetch` ingests arbitrary web content into agent context. All Phase 2 outputs are classified **L4 Verify-first** per the getting-started trust hierarchy — never treat fetched docs as authoritative absent cross-check against L3 (project code / tests) or L2 (design / plan). The citation + implement-from-source protocol **is** the verify-before-use duty.
- **Banned-sources rationale:** Stack Overflow / Medium / dev.to / personal blogs and random READMEs vary wildly in accuracy, age, and author expertise. Ingesting them widens prompt-injection attack surface (adversarial content disguised as sample code). They are permitted only as secondary corroboration, never as the cited authority.
- **Implicit domain trust:** the skill trusts doc domains listed in `detect-stack.md`. Per DEC-5, the `WebFetch(domain:…)` allowlist in `.claude/settings.local.json` grows **incrementally** — one domain per doc host — rather than via a blanket `WebFetch(*)` grant. This keeps the attack surface explicit and auditable.
- Recommend running `crucible:siege` on changes produced through this skill when the change is public-facing, given the external-input surface.