blueprint-first

name

blueprint-first

description

Guide any engineering task — building, fixing, expanding, refactoring, investigating — like a senior engineer at a big company. Teaches the thinking process, not just rules. Study first, plan properly, implement with discipline. Use this skill whenever the user mentions "follow the patterns", "replicate the architecture", "proper system design", "production-ready plan", "do it properly", "don't hardcode", "build it like they would", "find the root cause", "fix it properly", "don't just patch it", "expand this feature", "refactor this", "how does this work", or asks for any engineering work to follow existing conventions exactly. Also trigger when the user is frustrated that previous work was half-baked, used hardcoded values, created workarounds, suppressed lints, or didn't follow the repo's architecture. Even if the user just says "plan this properly" or "I want it done right" or "check the codebase first", use this skill. When in doubt, prefer this skill — studying the codebase first never makes anything worse.

Proper Engineering

Think like a senior engineer. Not "follow these rules" — ask the questions a senior engineer asks themselves before every decision. The rules emerge from the thinking.

Why This Exists

You optimize for speed. You jump to solutions. A senior engineer slows down and asks questions first. This skill teaches that thinking process.

---

Do NOT write code, propose fixes, or suggest architecture until you have studied the relevant code and documented what you found. Reading the codebase is not prep work — it IS the first deliverable.

---

Before Anything: Is This Trivial?

• "Does this change affect anything beyond the file I'm editing?"
• "Could this break something I'm not looking at?"
• "Do I fully understand the context, or am I assuming?"

If all three are "no" — read the file, read the tests, make the change, run the tests. The moment anything surprises you, escalate to the full workflow.

---

What Kind of Work Is This?

Task Type	Workflow	The Question That Identifies It
New feature (with analog)	references/blueprint-mode.md	"Does something like this already exist that I can study?"
New feature (no analog)	references/vocabulary-mode.md	"Nothing similar exists — how does this repo introduce new concepts?"
Bug fix	references/bug-fix.md	"Something's wrong — where does the data first become incorrect?"
Expand existing feature	references/expanding-features.md	"This works today — how do I add to it without breaking what exists?"
Refactor	references/refactoring.md	"The structure needs to change — how do I prove behavior is preserved?"
Investigation	references/investigation.md	"I don't understand how this works yet — what specific question am I answering?"
Remove/deprecate	references/removing-code.md	"This needs to go — what depends on it that I can't see?"

If unsure: Start with Investigation.

---

Engineering Stages

Read references/engineering-stages.md. For each stage, ask: "Does this feature have implications here?" Skip stages because they genuinely don't apply, not because you're in a hurry.

---

Implementation: The Questions That Matter

Question	If Yes	Guide
"If a new variant is added tomorrow, does my code handle it automatically?"	If not → you're hardcoding	references/never-hardcode.md
"Am I fixing this at the source, or patching where I noticed it?"	If patching → pipeline is broken	references/no-inline-workarounds.md
"Does this codebase already have infrastructure for this?"	If yes → extend it	references/reusing-patterns.md
"Where do files like this live? How are they named?"	Don't guess → look	references/file-structure.md
"Why is this lint firing?"	It's telling you something real	references/lint-and-quality.md
"If this breaks, how quickly will I know?"	If not fast → test after every change	references/incremental-development.md
"Am I rationalizing a shortcut?"	If yes → stop	references/gotchas.md

---

Before Writing Any Code

• "What does this code actually do?" Read the file.
• "What tests exist?" Read them.
• "What's the closest analog?" Use it as your template.
• "Who depends on this?" Trace the callers.
• "What do the conventions say?" Read CLAUDE.md. Follow it.
• "How do I verify this works?" Know the command. Run it after every change.

---

Quality of Thinking

Read these during design and implementation — they shape HOW you think, not just WHAT you build:

Guide	What It Teaches
references/auditors.md	6 internal voices (Linus, Scale, Simplicity, New Hire, 3AM, Pride) + 7 design taste questions from Ousterhout + when to use auditors vs tools
references/thinking-disciplines.md	Verify each step, explore before committing, backtrack when something feels wrong

---

The Final Question

"If someone who wasn't in this conversation reads what I produced — can they act on it correctly?"

If no, the work isn't done.

---

Do not jump to implementation without a plan. If the user wants to proceed:

• TDD decomposition → writing-plans
• Direct execution → executing-plans or subagent-driven-development
• Audit first → plan-review-board or audit-plan