| name | coding-guidelines |
| description | Plan, design, or review software changes with structured tradeoff analysis across architecture, implementation quality, validation, and performance, surfacing 2-3 options per concern with explicit recommendation. Triggers: 'review this code', 'PR review', 'how should I design', 'compare these approaches', 'is this approach OK', evaluating two or more realistic implementation strategies, or any non-trivial decision. Skip for typo/rename/format edits or pure prose. |
| license | AGPL-3.0-only |
| metadata | {"author":"marcodsl","tags":"architecture, code-review, planning, refactoring, testing, design","version":3} |
Coding Guidelines
Default workflow for code review, design, and engineering decisions. For each concern, surface the concrete problem, compare 2-3 realistic options with tradeoffs, recommend one, and ask the user to confirm before moving on. No silent picks.
- Reviewing code, a PR, a diff, or a snippet the user wants feedback on.
- Designing or architecting a feature, module, boundary, interface, refactor, workflow, or dependency.
- Choosing between two or more implementation approaches.
- Evaluating validation, testing, error handling, performance, or rollout tradeoffs before writing code.
- Any technical decision that benefits from explicit options and a recommended direction.
<do_not_use_when>
- Small direct fixes, typos, renames, formatting, or prose-only edits.
</do_not_use_when>
<governing_rule>
Lead with the highest-risk issue first. Recommend one option, present 2-3 alternatives including "do nothing" when reasonable, and pause for the user to confirm before moving to the next concern.
</governing_rule>
<working_method>
- Infer or ask for task type (Planning, Design, Architecture, Review) and depth (BIG CHANGE for staged interactive review; SMALL CHANGE for one focused question per stage).
- Ask about timeline, scope, and scale only when those priorities would change the recommendation.
- Walk the four stages in order: architecture, implementation quality, validation, performance.
- Pause after each meaningful section for feedback before continuing.
</working_method>
- Value DRY when duplication creates drift, fragmented ownership, or real maintenance cost.
- Treat validation and testing as required; scale coverage with risk and blast radius.
- Prefer explicit requirements, boundaries, data flow, and error handling over cleverness.
- Handle edge cases, rollout concerns, failure modes, and operational risk before polish.
- Avoid fragile shortcuts and avoid abstractions that do not remove real complexity.
1. Architecture and system design: boundaries, coupling, data flow, scalability, single points of failure, auth and security boundaries, requirements clarity, assumptions.
2. Implementation quality: organization, duplication, edge cases, error handling, technical debt, over- or under-engineering, readability, maintainability.
3. Validation and test strategy: acceptance criteria; unit, integration, and e2e coverage; assertion strength; failure paths; rollback paths; test scope vs risk.
4. Performance and scalability: N+1 access, memory usage, caching, complexity, capacity limits, whether the risk is worth fixing now.
For each concern or decision point:
- Lead with the highest-risk issues; defer minor nits.
- Reference files, lines, requirements, or subsystems when available.
- Present the recommended option first, then alternatives including "do nothing" when reasonable.
- For each option, state effort, risk, impact on other code, and maintenance burden.
- Label items so the user can answer unambiguously, for example `Issue 2, Option A`.
- Ask whether the user agrees or wants a different path before moving to the next stage.
<review_checklist>
- Established task type, depth, scope, timeline, and scale when they matter.
- Covered architecture, implementation quality, validation, and performance in order.
- For each major concern: stated problem, options, tradeoffs, recommendation, asked for confirmation.
- Ranked risks before minor issues and tied recommendations to the user's priorities.
</review_checklist>
