source-driven-development

Source-Driven Development

Overview

Verify the source before you write the change. For oviney/blog, that means combining official upstream documentation with repo-local truth such as CLAUDE.md, package.json, playwright.config.ts, and the existing skill/command layer. Official docs tell you what a tool supports; the repo tells you which subset this project actually uses.

When to Use

• Updating Jekyll, Liquid, Playwright, Lighthouse, Pa11y, or GitHub Actions guidance
• Creating or revising skill docs that point agents to concrete commands
• Writing reusable examples that other agents will copy
• Resolving whether a pattern is current, deprecated, or unsupported in this repo
• Reviewing docs that were likely written from memory rather than verified sources

The Rule: Source-Backed, Repo-Ratified

A recommendation is only safe when both checks pass:

1. Source-backed — supported by official docs or a first-party reference
2. Repo-ratified — consistent with this repo's actual commands, files, and protected boundaries

If upstream docs suggest a command the repo does not use, prefer the repo.

Verification Workflow

Step 1: Detect the Local Stack

Read the repo files that define the real environment:

- Gemfile / README / CLAUDE.md for Jekyll workflow
- package.json for executable npm scripts
- playwright.config.ts for browser test behavior
- lighthouserc.json for performance thresholds
- SECURITY.md for security posture

State the result explicitly before documenting anything:

STACK DETECTED:
- Jekyll site validated with `bundle exec jekyll build`
- Playwright tests via `npm run test:playwright`
- Accessibility checks via `npm run test:a11y`
- Lighthouse checks via `npm run test:lighthouse`
- Security audit via `npm run test:security`

Step 2: Fetch the Smallest Authoritative Source

Use the exact upstream page that governs the change:

Avoid tutorial blogs and generic AI summaries as primary sources.

Step 3: Reconcile with Repo Constraints

Ask the repo-specific questions that generic docs cannot answer:

• Is the command present in package.json?
• Does the repo already encode a preferred workflow in CLAUDE.md, AGENTS.md, or the relevant skill file?
• Does the change cross a protected or governance surface?
• Does the repo intentionally omit a tool (for example generic lint or typecheck defaults)?

Step 4: Write the Recommendation

Prefer wording like this:

Official docs support X.
This repo implements it via Y.
Therefore the doc should tell agents to run Z.

Conflict Handling

Surface conflicts instead of silently choosing one side:

CONFLICT DETECTED:
Upstream examples use a generic build command,
but oviney/blog validates changes with `bundle exec jekyll build`.

Decision:
Keep the repo command in local docs and cite the upstream source only for
behavior, not for the command wrapper.

Citation Rules for This Repo

• Cite upstream sources when they justify framework behavior or terminology
• Cite local files when they justify workflow, commands, paths, or boundaries
• If something is unverified, say so plainly rather than inventing certainty
• Do not turn unsupported tooling into a required default

Common Rationalizations

Red Flags

• Generic commands appear without proof from local files
• A doc cites upstream examples but ignores repo rules
• The recommendation assumes tools the repo does not install or run
• The writer cannot name the local file that validates the command
• Conflicts between upstream docs and repo practice are hidden

Verification

After writing or updating a source-driven doc:

• The repo files defining the command or workflow were read first
• The upstream reference is first-party and specific to the feature
• Every recommended command exists in this repo
• No unsupported default tooling was introduced
• Repo-specific constraints override generic examples where needed
• Any unresolved gaps are explicitly marked as unverified

Related Files

• ../../../package.json — local QA and security commands
• ../../../playwright.config.ts — local Playwright runtime behavior
• ../../../lighthouserc.json — local Lighthouse thresholds
• ../context-engineering/SKILL.md — how to load only the right sources