name: software-engineering description: Guides systematic code changes through planning, implementation, and verification phases while enforcing architectural patterns. This skill should be used when the user asks to "implement a feature", "make changes", "refactor code", "fix a bug", "design patterns", "architecture", "code organization", or starts a new development task. user-invocable: true disable-model-invocation: false

Software Engineering

Core Principles

Requirements, Not Solutions

Users should specify WHAT they need, not HOW to build it.

When given underspecified requests, fill in blanks with probable defaults from training data, which may not align with actual requirements. Always clarify requirements before implementing.

Respect the Spec

Identify what must NOT change before changing anything.

Immutable boundaries include:

• Public APIs and module interfaces
• External system integrations
• Test contracts (don't delete tests to make them pass)
• Documented constraints and specifications
• Behavior that clients depend on

Preparatory Refactoring

Make the change easy, then make the easy change.

Separate semantics-preserving refactoring from behavior-changing implementation. This makes both easier to review and understand.

Walking Skeleton

Build end-to-end first, then refine.

Implement a minimal but complete version that connects all components before perfecting individual pieces. A rudimentary but complete system provides more valuable feedback than polished but disconnected components.

Development Workflow

Phase 1: Planning

Before writing any code:

1. Gather context — Understand project structure, existing patterns, relevant files
2. Define requirements — Desired behavior, constraints, what should NOT change
3. Create a plan — Code structure, testing approach, design decisions
4. Ask questions — Resolve ambiguities during planning, not implementation

Phase 2: Implementation

Follow this order:

1. Preparatory refactoring — Semantics-preserving changes first, committed separately
2. Walking skeleton — Minimal end-to-end functionality before optimizing
3. Implementation + tests — Write together, focused on behavior
4. Run tests — Never consider complete without passing tests

Phase 3: Verification

Before considering complete:

1. Correctness — Tests pass, requirements met, no breaking changes
2. Quality — Files under ~50KB, follows patterns, no duplication (Rule of Three)
3. Iterate — One focused change at a time, verify improvement

For detailed workflow guidance, see references/workflow-phases.md.

When to Stop and Reconsider

Stop digging when:

• Solution is becoming increasingly complex
• Adding workarounds or hacks
• Tests fail suggesting fundamental design issues
• Caught in debugging loops trying random fixes
• Approach conflicts with existing architecture

Then:

1. Acknowledge the difficulty explicitly
2. Explain why the current approach is problematic
3. Propose alternatives with pros/cons
4. Ask for guidance on design decisions

For systematic debugging approaches, see references/debugging.md.

Creating Documents

When asked to create documents:

• Plans go in ./plans/ directory (move to ./plans/completed/ after implementation)
• Research and reference material go in ./references/ directory

References

• references/workflow-phases.md — Detailed planning, implementation, verification guidance
• references/architectural-patterns.md — DI patterns, code organization by language
• references/debugging.md — Scientific debugging, handling different scenarios