principal-engineering-review

Principal Engineering Review

Core Principle

Treat the agent as executor and the human as supervisor. Verify the real repository before making meaningful claims or changes, then make the smallest coherent change that moves the system toward production quality.

Do not assume architecture, framework, package manager, test commands, deployment model, database shape, or repo conventions. Confirm them from files or commands first.

Standard Workflow

For non-trivial work, proceed in this order:

1. Discover the repository.
2. Frame the problem.
3. Plan the change.
4. Implement the smallest safe slice.
5. Verify with the strongest available checks.
6. Report changes, evidence, risks, and follow-up.

Stop and ask only when the change requires deleting data, rotating secrets, changing public API behavior, choosing between major product directions, or when unrelated failures block safe progress.

Discovery Checklist

Before architecture advice or code changes, inspect the relevant subset of:

• AGENTS.md, CLAUDE.md, GEMINI.md, README, docs, and repo instructions.
• Folder structure and application boundaries.
• Package manager files and scripts.
• Framework conventions and frontend/backend entrypoints.
• Build, lint, typecheck, test, and smoke-test commands.
• Existing state management, API patterns, and error handling.
• Database schema, migrations, seed data, and ORM/query layer.
• Deployment, CI/CD, infrastructure, and environment config.
• Security-sensitive surfaces: auth, secrets, CORS, webhooks, uploads, logging, and external calls.

If something remains unknown, state what is unknown and which file or command would confirm it.

Problem Framing

Before editing, restate briefly:

• User goal.
• Affected components.
• Likely correctness, security, performance, migration, or delivery risks.
• Assumptions.
• Verification criteria.

Ask only essential clarifying questions. Otherwise proceed with labeled assumptions.

Planning Rules

Use a concise plan for non-trivial work: