helderberto/source-driven

Source-Driven Development

Never rely on training data for API usage. Read the actual source of truth.

Pre-loaded context

• Dependencies: !cat package.json | grep -E '"dependencies"|"devDependencies"' -A 50 | head -60

Workflow

1. Identify Dependencies

• Read package.json (or equivalent manifest) for exact versions
• Note the exact version of each library involved in the task

2. Fetch Official Docs

For each dependency involved:

1. Find the correct docs URL for that specific version (not "latest")
2. Fetch the relevant API page using WebFetch
3. Extract: function signatures, required params, return types, breaking changes

If docs are unavailable or ambiguous, read the library source in node_modules/.

3. Implement from Docs

• Use only APIs confirmed in fetched docs
• Match function signatures exactly (param order, types, defaults)
• If a doc page confirms the API: proceed
• If you cannot verify an API: mark it // UNVERIFIED: could not confirm in docs for v{version}

4. Cite Sources

Add a brief comment on non-obvious API usage:

// Ref: https://docs.example.com/v3/api#method

Only cite when the usage is surprising or version-specific. Don't over-comment obvious calls.

Anti-Rationalization

| Excuse | Rebuttal | |---|---| | "I know this API from training data" | Training data may be outdated or wrong. Check the version. | | "The docs are too slow to fetch" | One fetch now prevents hours debugging a hallucinated API later. | | "It's a minor utility, no need to check" | Minor utilities have breaking changes between versions too. | | "I'll verify later" | Unverified code compounds. Verify now or mark UNVERIFIED. |

Rules

• NEVER guess API signatures — fetch or read source
• NEVER assume "latest" docs match the installed version
• Always mark unverified claims with // UNVERIFIED
• Prefer node_modules/ source over training knowledge when docs unavailable
• Don't cite every line — only non-obvious or version-sensitive usage

Error Handling

• Docs URL returns 404 → try GitHub repo README, then node_modules/ source
• Version not found in docs → use closest version docs + mark // UNVERIFIED: docs for v{closest}, installed v{actual}
• WebFetch blocked/unavailable → read node_modules/{pkg}/README.md or type definitions