Docs First Implementer

---
name: docs-first-implementer
description: "MANUAL-ONLY; never auto-invoke. Implement against frameworks, libraries, or external services by first identifying the EXACT versions installed in this repo and reading the matching documentation — official docs, local node_modules/vendored docs, changelogs — before writing any code. Summarizes only the syntax relevant to the task, implements, then verifies with the project's tests/build/lint. States uncertainty explicitly when docs for the pinned version are unavailable instead of guessing from training data. Use when implementing a feature that touches a framework or library API, when an API may have changed across versions, when integrating an external SDK or service, or after being burned by an API that \"should exist\" but doesn't in the installed version."
disable-model-invocation: true
---

# Docs-First Implementer

Terms: **API** means application programming interface; **ORM** means
object-relational mapper; **UI** means user interface; **SDK** means software
development kit; **AI** means artificial intelligence; **CI** means
continuous integration.

## Purpose

Eliminate the "implemented against a remembered API" failure mode: code
written for a version the project does not have, deprecated options,
hallucinated methods. The discipline is version → docs → summarize → implement
→ verify: pin the exact installed version, read documentation that matches
it, extract only the task-relevant syntax, implement, and prove it with the
project's own verification commands. Where matching docs cannot be found,
uncertainty is stated as a first-class output, not papered over.

## Use When

- Use when: implementing a feature that leans on a framework or library API —
  routing, ORM queries, auth middleware, UI library components, SDK calls.
- Use when: the library is fast-moving or the API surface differs across
  majors (build tools, meta-frameworks, cloud SDKs, AI SDKs).
- Use when: a previous attempt failed with "X is not a function" or
  deprecation warnings — symptoms of version drift.
- Do NOT use when: the change is pure project-internal logic touching no
  external API — normal implementation discipline suffices.
- Do NOT use when: the task is diagnosis of an unknown-cause failure — that
  is `systematic-debugger` *(manual-only)* (which may hand off here once the fix touches a
  library API).
- Do NOT use when: the human asked for test-first development explicitly —
  run `tdd-engineer` *(manual-only)* as the outer loop; this skill governs the docs step
  inside it.

## Inputs to Inspect

1. Version manifests: `package.json` + lockfile, `requirements.txt`/
   `pyproject.toml`/`poetry.lock`, `go.mod`, `*.csproj`, `Gemfile.lock` —
   the LOCKED version, not the semantic-versioning (semver) range.
2. The documentation matching that version: versioned official docs, the
   installed package's own `README`/`docs/` in `node_modules` or site-packages,
   changelog/migration guides between the docs' version and the installed one.
3. Existing usage of the same library in this repo — the project may already
   have a sanctioned pattern (wrapper, config, error handling) to follow.
4. The project's verification commands: test runner, build, lint, typecheck
   (from package scripts, CI config, or CLAUDE.md).

## Workflow

For any user-facing build choice, define terms and each viable path's purpose;
compare case-specific pros/cons and money, setup, and maintenance costs (mark
unknowns). Recommend one and why, then ask one atomic decision question. If a
deciding fact is missing, ask only for that fact this turn. A choice does not
authorize execution.

Explicit human invocation selects this execution-capable skill; it does not
expand the allowed target or activate Task-Authorized Local Implementation
(TALI). TALI is a separate route that requires its own classification and
activation under the [skill-generation standard](../../../docs/skill-generation-standard.md#5-least-privilege--side-effects).
Use applicable existing user grants without repeated consent. Before a
state-changing command, confirm its actual files, environment and effects fit
those grants; if authority is absent, propose the operation and obtain it
before proceeding.

1. **Pin the exact version.** Read the lockfile, not the manifest range.
   Record: library, locked version, and where it is imported today.
2. **Find version-matching docs.** Preference order: versioned official docs
   for that exact major/minor → the installed package's bundled README/types/
   docs → changelog diff from the nearest documented version. Record which
   source was actually used.
3. **Summarize task-relevant syntax only** — the 3–10 API facts this task
   needs (signatures, options, defaults, error behavior), each attributed to
   its source. No general tutorial prose.
4. **Check repo precedent.** If the repo already wraps or configures this
   library, follow that pattern; deviating from it is a decision to surface,
   not a default.
5. **Declare uncertainty before coding.** Anything the docs did not answer
   goes in an "unverified" list — implemented defensively and called out.
6. **Implement** the minimal change consistent with the summarized syntax and
   repo conventions.
7. **Verify** with the project's own commands (tests, build, lint,
   typecheck). Report the exact commands and real results. A missing
   verification path is reported, not silently skipped.

## Output Format

When asking for a build choice, show the explained options and justified
recommendation before the one question.

```
DOCS-FIRST IMPLEMENTATION — <task>
Version pin: <library>@<locked version> (source: <lockfile>)
Docs consulted: <source + version — e.g. official vX.Y docs, node_modules README,
                 CHANGELOG X.Y→X.Z>
Relevant syntax: <the 3–10 facts used, each with source>
Repo precedent followed: <pattern/file, or "none exists">
Unverified assumptions: <each with mitigation> | None
Change: <files touched, summary>
Verification: <exact commands + actual results>
```

## Validation Checklist

- [ ] User-facing build choices explain terms, reasons, costs or unknowns,
      pros/cons, and a justified recommendation before one atomic question.
- [ ] Version taken from the LOCKFILE (or equivalent resolved source).
- [ ] Every API call in the change traces to the syntax summary; every
      summary line traces to a named doc source.
- [ ] Docs source version matches the installed version, or the gap is
      bridged via changelog and said so.
- [ ] Repo's existing wrapper/pattern for this library followed or the
      deviation justified.
- [ ] Verification commands actually run, with real output reported —
      failures included.
- [ ] Unverified assumptions listed explicitly ("None" written deliberately).

## Gotchas

- The manifest says `^4.0.0` but the lockfile resolved 4.9.2 — features and
  deprecations live in that gap. Always the lockfile.
- Docs sites default to "latest"; a URL without a version selector is a trap.
  Prefer the version switcher or the installed package's own files.
- Two majors of the same library can coexist (transitive vs direct); confirm
  which one the import resolves to before trusting either changelog.
- Training-data memory of an API feels identical to knowledge of it. The tell:
  you didn't read it today. If it's not in the syntax summary, don't type it.
- AI-era libraries (SDKs, frameworks <2 years old) change signatures between
  minors; changelog reading is not optional there.
- Local docs in `node_modules` describe the installed version by definition —
  they beat a newer, shinier docs site.

## Stop Conditions

- The skill was selected automatically rather than explicitly invoked by the
  human: do not execute it. An agent may recommend the named manual skill.
- A write, Git/network operation, database command or test side effect exceeds
  the applicable human grant: stop that operation and obtain the missing scope.
  Existing authorized operations do not need the same permission again.

- No documentation for the installed version can be located and the changelog
  gap is unbridgeable → stop and present options (upgrade, spike, proceed
  with declared risk) rather than implementing from memory. Define a version
  upgrade and a bounded spike, explain why each could resolve the gap, give
  case-specific benefits and drawbacks and purchase, setup, and upkeep costs
  or unknowns, then recommend a route and explain why. Do not code past the
  unresolved gap while waiting for a required decision.
- The docs reveal the requested approach is deprecated or unsafe in this
  version → surface before implementing, don't silently substitute.
- The correct implementation requires a version bump → that is a dependency
  change with its own blast radius; get approval via
  `change-classification-gate`/`human-approval-boundary` rather than bundling it.
  Explain the current and proposed versions, migration and security reasons,
  benefits and drawbacks, money/time/maintenance costs, and why the recommended
  version fits this task before asking for any missing authority.
- Verification commands fail for pre-existing reasons unrelated to the change
  → report the baseline failure; do not "fix" unrelated tests to get green.

## Supporting Files

- [references/version-doc-checklist.md](references/version-doc-checklist.md) —
  per-ecosystem lockfile locations, doc-source preference tables, and
  changelog-bridging tactics.
- `evals/evals.json` — trigger + behavior cases.
- `evals/trigger-evals.json` — discrimination against `tdd-engineer` and
  `systematic-debugger` (implementation cluster).