Software Engineering Foundations

Universal methodology for professional software engineering practice. Language-agnostic foundations that apply regardless of tech stack.

Core Principle

Engineering excellence is methodology, not heroics. Systematic approaches beat clever improvisation. These skills encode battle-tested processes for situations where "just figure it out" leads to wasted time and missed root causes.

When to Use

Load this skill when:

Facing a bug that resists simple fixes
Need to refactor safely without breaking things
Reviewing code (yours or others')
Production is on fire
Deciding what technical debt to address
Taking ownership of code you don't fully understand

Don't use for: Language-specific issues (use language packs), algorithm design (use CS fundamentals), infrastructure/deployment (use DevOps packs).

How to Access Reference Sheets

IMPORTANT: All reference sheets are in the SAME DIRECTORY as this SKILL.md.

When this skill is loaded from: skills/using-software-engineering/SKILL.md

Reference sheets like complex-debugging.md are at: skills/using-software-engineering/complex-debugging.md

NOT at: skills/complex-debugging.md (WRONG PATH)

Routing by Situation

Horrible Bugs

Symptoms:

Bug resists simple fixes
"I've tried everything"
Intermittent failures
Works on my machine
Can't reproduce reliably
Multi-system interactions
Heisenbugs (changes when observed)
Race conditions suspected

Route to: complex-debugging.md

Why: Systematic debugging methodology using scientific method. Adapted for Claude's strengths (fast codebase reading, pattern recognition) and limitations (no interactive debuggers).

Integration: For domain-specific bugs, use this methodology THEN hand off to specialists:

PyTorch issues → yzmir-pytorch-engineering (debug-oom, debug-nan)
RL training → yzmir-deep-rl (rl-debugging)
Simulation chaos → bravos-simulation-tactics (debugging-simulation-chaos)
ML production → yzmir-ml-production (production-debugging-techniques)

Safe Code Transformation

Symptoms:

"This code needs cleanup"
Large refactoring needed
Scared to change working code
Technical debt paydown
Architecture migration
"How do I change this without breaking it?"

Route to: systematic-refactoring.md

Why: Safe, incremental transformation methodology. Preserves behavior while improving structure.

Pairs with: technical-debt-triage.md to decide WHAT to refactor, this skill for HOW.

Code Review

Symptoms:

Reviewing someone's PR
Want feedback on your code
"Is this code good?"
Pre-merge quality check
Teaching through review
Review feels overwhelming

Route to: code-review-methodology.md

Why: Systematic review process - what to look for, in what order, how to give actionable feedback.

Pairs with: codebase-confidence-building.md when reviewing unfamiliar code areas.

Production Fire

Symptoms:

Production is down
Users are affected NOW
Incident in progress
Need to triage quickly
Postmortem needed
"Everything is broken"

Route to: incident-response.md

Why: Fire-fighting methodology - contain, diagnose, fix, learn. Keeps you calm under pressure.

Note: Use DURING incidents for process. Use complex-debugging.md for the debugging portion.

Technical Debt Decisions

Symptoms:

"Should we fix this?"
Prioritizing cleanup work
Debt is slowing us down
Sprint planning for maintenance
"Everything needs fixing"
Justifying refactoring to stakeholders

Route to: technical-debt-triage.md

Why: Systematic identification, categorization, and prioritization. When to pay down vs. live with debt.

Pairs with:

systematic-refactoring.md for HOW to fix
codebase-confidence-building.md to understand debt in unfamiliar areas

Building Codebase Confidence

Symptoms:

"I own this but don't fully understand it"
New to a codebase
Taking over from someone
~70% confidence, need more
"Where do I even start?"
Undocumented system

Route to: codebase-confidence-building.md

Why: Systematic exploration to internalize a system you'll maintain. Different from archaeology (analysis) - this is about building working mental models.

Pairs with:

technical-debt-triage.md - confidence reveals debt
code-review-methodology.md - review helps you learn

Related but different: axiom-system-archaeologist is for architecture ANALYSIS. This skill is for INTERNALIZATION of systems you'll maintain long-term.

Cross-Cutting Scenarios

Taking Over a Codebase

codebase-confidence-building.md - Build mental model
technical-debt-triage.md - Identify what needs fixing
systematic-refactoring.md - Execute improvements

Inherited Bug in Unfamiliar Code

codebase-confidence-building.md - Understand relevant subsystem
complex-debugging.md - Apply debugging methodology

Major Refactoring Project

technical-debt-triage.md - Prioritize what to fix
systematic-refactoring.md - Safe transformation process
code-review-methodology.md - Validate changes

Production Incident with Unknown Root Cause

incident-response.md - Contain and triage
complex-debugging.md - Find root cause
incident-response.md - Postmortem

Ambiguous Queries - Ask First

When situation unclear, ASK ONE clarifying question:

"Help me with this code" → Ask: "What's the goal? Debug a bug? Review quality? Refactor safely? Understand it?"

"This is a mess" → Ask: "Do you need to debug something broken, or clean up working-but-ugly code?"

"Fix this" → Ask: "Is it broken (debugging) or just ugly (refactoring)?"

Never guess. Ask once, route accurately.

Common Routing Mistakes

Symptom	Wrong	Correct	Why
"Code needs cleanup"	complex-debugging	systematic-refactoring	Not broken, needs transformation
"Bug in code I don't know"	complex-debugging only	confidence-building THEN debugging	Understand before debugging
"Production down"	complex-debugging	incident-response THEN debugging	Contain first
"Should we fix this debt?"	systematic-refactoring	technical-debt-triage	Decide WHAT before HOW
"Review this PR"	complex-debugging	code-review-methodology	Review ≠ debugging

Reference Sheet Catalog

Sheet	Purpose
complex-debugging.md	Scientific method for horrible bugs
systematic-refactoring.md	Safe incremental code transformation
code-review-methodology.md	How to review systematically
incident-response.md	Production fire methodology
technical-debt-triage.md	Identify, prioritize, decide
codebase-confidence-building.md	Internalize systems you maintain

Cross-Plugin Integration

This plugin provides methodology. Other plugins provide domain expertise. Use together:

This Plugin	Pairs With	For
complex-debugging	`yzmir-pytorch-engineering`	ML debugging (OOM, NaN)
complex-debugging	`yzmir-deep-rl:rl-debugging`	RL training issues
complex-debugging	`ordis-quality-engineering`	Flaky tests, observability
complex-debugging	`yzmir-systems-thinking`	Systemic/feedback loop bugs
incident-response	`ordis-quality-engineering`	Chaos engineering, load testing
technical-debt-triage	`axiom-system-architect`	Architecture-level debt
technical-debt-triage	`ordis-quality-engineering`	Quality metrics, static analysis
codebase-confidence-building	`axiom-system-archaeologist`	Formal architecture analysis

Pattern: Use this plugin's methodology to structure your approach, then hand off to domain specialists for specific technical guidance.

Claude-Specific Adaptations

All reference sheets are adapted for Claude's unique position:

Claude's Strengths (lean into these):

Fast codebase reading - can scan entire codebases quickly
Pattern recognition - spot similar bugs across files
Exhaustive search - check every occurrence of a pattern
No fatigue - systematic processes don't tire Claude out
Memory within session - track hypotheses and experiments

Claude's Limitations (work around these):

No interactive debuggers (gdb, pdb step-through)
Can't observe runtime state directly
Must ask user for information Claude can't get (logs, user actions, production state)

When to ask the user: Sooner rather than later, but ONLY if you can't get the information yourself. Check logs, code, git history, tests first.