Dev Guardrails

This skill exists because LLMs consistently make a set of predictable, preventable mistakes during development tasks. These guardrails are not suggestions — they are corrective constraints derived from real failure patterns. The goal is to eliminate regressions, preserve existing work, ensure every change is deliberate, tested, context-aware, and coherent with the product as a whole.

Read this entire file before writing any code or making any changes. Then read the relevant reference files in references/ based on the task at hand.

Core Philosophy

Every change you make exists within a living system. Code is not isolated — it connects to other files, services, databases, user flows, and real humans using the product. A single edit can cascade through an entire architecture. Your job is not just to make something work in isolation, but to make it work within the whole system without breaking what already exists.

Think like a senior engineer AND a product owner maintaining a production system with real users and real data, not like an assistant generating code snippets.

Every feature exists within a product that humans use. Before writing code, ask: "Does this make sense to a user? Is this consistent with how the rest of the product works? Would a human product designer approve this? Does this work with the data that already exists in production?"

Session Start Protocol

At the beginning of every new session on a project, before any task execution:

1. Read the project root with view to understand current structure
2. Read core documentation: TODO.md, ARCHITECTURE.md, CHANGELOG.md, README.md (whichever exist)
3. Check recent git history (git log --oneline -20) to understand what changed recently
4. Read any .env.example to understand current configuration requirements
5. If the user references previous work, verify it against actual files — never trust conversation memory over filesystem state

This protocol ensures continuity across sessions and prevents the "fresh start amnesia" where each session ignores accumulated decisions.

Phase 0: Product & System Thinking

This phase is mandatory. It runs BEFORE any code planning. Most implementation failures are not code bugs — they are product-level incoherence that no amount of testing can fix.

0.1 — Understand the Product Context

Before touching code, answer these questions:

• What is this feature's purpose from the user's perspective? Not the technical implementation — the user's mental model. What problem does it solve for them?
• Where does this feature live in the product's information architecture? Map the existing navigation, screens, overlays, modals, and settings. Where does this new thing fit?
• What already exists that overlaps with this? Search for existing functionality that does similar things. If a "preferences" overlay already exists and you're about to create a "settings" screen, you need to reconcile them.
• What is the user's journey to and from this feature? How do they get here? What do they do after? Does this flow make sense?

0.2 — Audit for Coherence

Before implementing any UI-facing change, perform a coherence audit:

1. Navigation audit: Map all current navigation paths (sidebar, menus, dropdowns, overlays). Identify where the new feature fits and whether existing paths need to be reorganized.
2. Naming audit: Are labels and terms consistent? If one screen calls it "Preferences" and another calls it "Settings," that's a product problem you need to flag — not perpetuate.
3. Grouping audit: Is related functionality grouped logically? Settings about the account should be together. Settings about the app's behavior should be together. Don't scatter related options across 3 different screens.
4. Duplication audit: Does the same control or option appear in multiple places? If so, either consolidate or establish a clear hierarchy (quick-access vs. full settings).

0.3 — Think About What's NOT Being Asked

This is the highest-leverage guardrail. When the user asks you to implement X, actively consider:

• What the user probably expects but didn't explicitly say. If they ask for a "user profile" page, they probably expect it to be accessible from the avatar/user menu — not a random sidebar link.
• What breaks or becomes inconsistent if you add X as-is. Adding a new settings page without reorganizing the existing preferences overlay creates a fragmented experience.
• What adjacent features need to be created or updated. If you add a "Referral Program" menu item as "Coming Soon," you should also add it to the project's TODO.md or roadmap.
• What a human product designer would question. "Why is account deletion in the settings page instead of the account page?" "Why are there two different places to change language?"

0.4 — Flag and Propose, Don't Just Execute

When you identify product-level issues:

1. State what you found — "The current structure has preferences split across two locations: the Preferences overlay (culling settings) and the Settings screen (other preferences). This creates a fragmented experience."
2. Propose a resolution — "I recommend consolidating all preferences into a single Preferences screen, organized by category."
3. Wait for confirmation on non-trivial restructuring — But do NOT silently implement a fragmented feature just because that's what was literally asked.

If the user's request would create a clearly inconsistent or confusing product experience, say so before implementing. It is always better to propose a coherent alternative than to faithfully implement something incoherent.

0.5 — System Impact Analysis

Before implementing any feature, trace its impact across the entire system:

User Flow → Navigation → Screen Layout → Components → State → API → Database → AI

Ask for each layer:

• Does this change require modifications here?
• Does this change conflict with what already exists here?
• Will existing features still work correctly after this change?
• Are there race conditions, state conflicts, or UX contradictions?

Document the impact analysis in your plan. If the impact is broader than the user might expect, explicitly call it out.

0.6 — Complexity & Impact Estimation

Before starting implementation, classify the task:

• Small (1-2 files, isolated change, no cross-feature impact) → Proceed after plan confirmation
• Medium (3-5 files, touches shared components or state) → Present plan with affected files and confirm
• Large (6+ files, cross-layer changes, navigation restructuring, schema changes) → Full impact analysis required. Explicitly tell the user: "This affects N files across M layers. Here's the breakdown. Want to proceed?"

Never silently execute a large change. The user deserves to know the scope before committing.

Phase 1: Understand Before Acting

Before writing a single line of code, complete these steps:

1.1 — Map the Context

• Read the project structure using view on the project root. Understand the folder hierarchy, naming conventions, and where things live.
• Read every file that will be affected by the change — not just the target file. If you're editing a component, also read its parent, its imports, its types, and any API routes it calls.
• Read adjacent features — if you're implementing a settings page, read the existing preferences, account, and navigation components too. You need the full picture.
• Identify the tech stack — frameworks, languages, ORMs, state management, styling approach, deployment target. Never assume.
• Check for existing patterns — how are similar things already done in this project? Follow those patterns unless explicitly told to deviate.

1.2 — Clarify Ambiguity

If anything is unclear about the request, ask before implementing. Common ambiguities that require clarificatio