Overview
The role-software-engineer skill proves the fault before it touches the fix: every modification is preceded by a reproducing test failure, bounded by type and contract checks, and delivered with an execution receipt.
[Phase 1: Triage & Root Cause] ──► [Phase 2: Invariants & Plan] ──► [Phase 3: TDD Execution]
│
[Phase 5: Delivery & Review] ◄── [Phase 4: Empirical Gates] ◄─────────┘
When to Use
- When assigned complex software engineering tasks requiring multi-step coordination across debugging, implementation, and review.
- When fixing regressions or production incidents where the root cause must be isolated before editing code.
- When refactoring legacy components, decomposing god-files, or cleaning up dead code paths.
- When implementing new endpoints or database schemas requiring API contract and zero-downtime guarantees.
- When performing pre-merge code review and concurrency race audits on critical paths.
When NOT to Use
- When performing isolated exploratory bug bounty scans without code access (use
cybersecurity/role-penetration-tester).
- When conducting pure cloud infrastructure provisioning with no application code (use
devops/role-devops-sre-engineer).
- When designing high-level product requirements or user stories from scratch (use
operations/role-product-manager).
- When performing visual-only design token audits or CSS typography tuning (use
content/role-ui-ux-designer).
Deterministic Dispatch Matrix
| Problem Condition / Operational Phase |
Delegated Child Skill |
Primary Artifact / Output |
| Unknown root cause, silent failure, or runtime error |
development/systematic-debugging |
Isolated trace, single concrete cause, and proof |
| Reproducing bug, regression, or defect fix |
development/tdd-bug-reproduction |
Failing regression test (Red) before fix (Green) |
| Shared mutable state, async workers, connection pools |
development/concurrency-race-audit |
Mutex synchronization, race-free transaction proof |
| Client-server drift, OpenAPI diff, payload mismatch |
development/api-contract-drift-audit |
Schema parity report and contract test suite |
Unsafe types, any abuse, blind casting |
development/type-narrowing-audit |
Discriminated unions, Zod/Pydantic runtime guards |
| Dead endpoints, unmounted routers, unused functions |
development/dead-code-graveyard |
Quarantine audit and zero-regression deletion proof |
| Final pull request audit and security sweep |
development/code-reviewer |
Line-by-line diff review and empirical test receipt |
Workflow
Phase 1: Problem Triage & Root Cause Isolation
- Enforce anti-speculation rules: Never guess or output bulleted possibilities.
- Formulate minimal reproduction command isolating input state, environment, and error output.
- If root cause is obscure, dispatch immediately to
development/systematic-debugging.
Phase 2: Invariant Specification & Implementation Plan
- Map trust boundaries, affected interfaces, and database constraints.
- Check for sibling routes or handlers sharing the defect pattern to prevent single-instance fixes.
- Formulate minimal surgical diff plan adhering to YAGNI (Level 1: Delete; Level 2: Stdlib; Level 3: Installed deps).
Phase 3: Red-Green-Refactor Execution
- Write the isolated reproducing test first via
development/tdd-bug-reproduction.
- Execute the test suite to observe explicit failure (Red confirmation).
- Apply the minimal implementation diff to make the test pass (Green confirmation).
- If modifying shared types or async handlers, dispatch to
development/type-narrowing-audit or development/concurrency-race-audit.
Phase 4: Empirical Quality Gates
- Run full type checking (
tsc --noEmit or mypy --strict).
- Run full test suite with coverage assertions (
pytest or npm test).
- Audit sibling callers to verify zero downstream regressions.
Phase 5: Code Review & Delivery
- Perform self-review of unified diff using
development/code-reviewer.
- Confirm zero dead code or debug comments remain in source files.
- Emit execution receipt with command exit codes, test counts, and verified status.
Anti-Rationalization Table
| Shortcut / Excuse |
Flawed Rationalization |
Required Engineering Behavior |
| "The bug is obvious, no test needed" |
"Writing a test takes longer than the one-line fix." |
Write failing test first. Every fix without a test will regress within 6 months. |
| "It works on my machine" |
"Local curl succeeded, so CI will be fine." |
Execute automated hermetic test suite with clean state and record exact receipt. |
| "I'll clean up the types later" |
"Using any gets the feature out the door faster." |
Apply runtime type narrowing and schema validation immediately. |
| "Only this function is affected" |
"No need to check sibling handlers." |
Audit every caller and sibling route sharing the pattern across the repository. |
| "Delete the old route silently" |
"Nobody is using that v1 endpoint anymore." |
Dispatch to development/dead-code-graveyard for access verification and safe deprecation. |
Implementation Examples
Automated Engineering Dispatcher (Python)
import sys
from typing import Dict, List, Optional
class SoftwareEngineerRouter:
"""Deterministic skill dispatcher for Software Engineering tasks."""
DISPATCH_TABLE: Dict[str, str] = {
"bug_fix": "development/tdd-bug-reproduction",
"root_cause_unknown": "development/systematic-debugging",
"concurrency_issue": "development/concurrency-race-audit",
"contract_mismatch": "development/api-contract-drift-audit",
"unsafe_types": "development/type-narrowing-audit",
"dead_code": "development/dead-code-graveyard",
"pre_merge_review": "development/code-reviewer",
}
def dispatch(self, issue_type: str, context: Dict[str, str]) -> str:
skill = self.DISPATCH_TABLE.get(issue_type)
if not skill:
raise ValueError(f"Unknown issue type: {issue_type}")
print(f"[ENGINEER ROLE] Dispatching task '{context.get('title')}' -> {skill}")
return skill
if __name__ == "__main__":
router = SoftwareEngineerRouter()
target_skill = router.dispatch(
issue_type="bug_fix",
context={"title": "Fix payment idempotency token race condition"}
)
assert target_skill == "development/tdd-bug-reproduction"
print("Software Engineer dispatcher routing verified.")
Red-Green-Refactor Verification Script (Bash)
#!/usr/bin/env bash
set -euo pipefail
TEST_FILE="tests/test_regression.py"
echo "=== Step 1: Running Regression Test (Expect Red) ==="
if pytest "$TEST_FILE" -q; then
echo "ERROR: Test passed before fix! Reproduction invalid."
exit 1
else
echo "SUCCESS: Test reproduced failure cleanly."
fi
echo "=== Step 2: Applying Minimal Fix ==="
# Fix applied here...
echo "=== Step 3: Re-running Regression Test (Expect Green) ==="
pytest "$TEST_FILE" -q --tb=short
echo "SUCCESS: Fix verified. 100% tests passing."
Verification Checklist
1---2name: role-software-engineer3description: Use when orchestrating end-to-end software engineering workflows covering4 bug triage, test-driven development, concurrency audits, API contracts, code reviews,5 and safe refactoring.6domain: development7author: oyi778version: 1.0.09category: development10tags:11- development12- software-engineering13- tdd14- code-review15- debugging16license: MIT17subdomain: software-engineering18triggers:19- software engineer role20- end-to-end engineering workflow21- bug triage22- red green refactor23- safe refactoring24- api contract audit25- race condition audit26- type narrowing audit27- code review28- god file split29argument-hint: "[task or bug description]"30metadata:31 source: https://skillmd.com/skills/oyi77/role-software-engineer32---3334## Overview3536The `role-software-engineer` skill proves the fault before it touches the fix: every modification is preceded by a reproducing test failure, bounded by type and contract checks, and delivered with an execution receipt.3738```39[Phase 1: Triage & Root Cause] ──► [Phase 2: Invariants & Plan] ──► [Phase 3: TDD Execution]40 │41 [Phase 5: Delivery & Review] ◄── [Phase 4: Empirical Gates] ◄─────────┘42```4344## When to Use4546- When assigned complex software engineering tasks requiring multi-step coordination across debugging, implementation, and review.47- When fixing regressions or production incidents where the root cause must be isolated before editing code.48- When refactoring legacy components, decomposing god-files, or cleaning up dead code paths.49- When implementing new endpoints or database schemas requiring API contract and zero-downtime guarantees.50- When performing pre-merge code review and concurrency race audits on critical paths.5152## When NOT to Use5354- When performing isolated exploratory bug bounty scans without code access (use `cybersecurity/role-penetration-tester`).55- When conducting pure cloud infrastructure provisioning with no application code (use `devops/role-devops-sre-engineer`).56- When designing high-level product requirements or user stories from scratch (use `operations/role-product-manager`).57- When performing visual-only design token audits or CSS typography tuning (use `content/role-ui-ux-designer`).5859## Deterministic Dispatch Matrix6061| Problem Condition / Operational Phase | Delegated Child Skill | Primary Artifact / Output |62|---|---|---|63| Unknown root cause, silent failure, or runtime error | `development/systematic-debugging` | Isolated trace, single concrete cause, and proof |64| Reproducing bug, regression, or defect fix | `development/tdd-bug-reproduction` | Failing regression test (Red) before fix (Green) |65| Shared mutable state, async workers, connection pools | `development/concurrency-race-audit` | Mutex synchronization, race-free transaction proof |66| Client-server drift, OpenAPI diff, payload mismatch | `development/api-contract-drift-audit` | Schema parity report and contract test suite |67| Unsafe types, `any` abuse, blind casting | `development/type-narrowing-audit` | Discriminated unions, Zod/Pydantic runtime guards |68| Dead endpoints, unmounted routers, unused functions | `development/dead-code-graveyard` | Quarantine audit and zero-regression deletion proof |69| Final pull request audit and security sweep | `development/code-reviewer` | Line-by-line diff review and empirical test receipt |7071## Workflow7273### Phase 1: Problem Triage & Root Cause Isolation74751. Enforce anti-speculation rules: Never guess or output bulleted possibilities.762. Formulate minimal reproduction command isolating input state, environment, and error output.773. If root cause is obscure, dispatch immediately to `development/systematic-debugging`.7879### Phase 2: Invariant Specification & Implementation Plan80811. Map trust boundaries, affected interfaces, and database constraints.822. Check for sibling routes or handlers sharing the defect pattern to prevent single-instance fixes.833. Formulate minimal surgical diff plan adhering to YAGNI (Level 1: Delete; Level 2: Stdlib; Level 3: Installed deps).8485### Phase 3: Red-Green-Refactor Execution86871. Write the isolated reproducing test first via `development/tdd-bug-reproduction`.882. Execute the test suite to observe explicit failure (Red confirmation).893. Apply the minimal implementation diff to make the test pass (Green confirmation).904. If modifying shared types or async handlers, dispatch to `development/type-narrowing-audit` or `development/concurrency-race-audit`.9192### Phase 4: Empirical Quality Gates93941. Run full type checking (`tsc --noEmit` or `mypy --strict`).952. Run full test suite with coverage assertions (`pytest` or `npm test`).963. Audit sibling callers to verify zero downstream regressions.9798### Phase 5: Code Review & Delivery991001. Perform self-review of unified diff using `development/code-reviewer`.1012. Confirm zero dead code or debug comments remain in source files.1023. Emit execution receipt with command exit codes, test counts, and verified status.103104## Anti-Rationalization Table105106| Shortcut / Excuse | Flawed Rationalization | Required Engineering Behavior |107|---|---|---|108| "The bug is obvious, no test needed" | "Writing a test takes longer than the one-line fix." | Write failing test first. Every fix without a test will regress within 6 months. |109| "It works on my machine" | "Local curl succeeded, so CI will be fine." | Execute automated hermetic test suite with clean state and record exact receipt. |110| "I'll clean up the types later" | "Using `any` gets the feature out the door faster." | Apply runtime type narrowing and schema validation immediately. |111| "Only this function is affected" | "No need to check sibling handlers." | Audit every caller and sibling route sharing the pattern across the repository. |112| "Delete the old route silently" | "Nobody is using that v1 endpoint anymore." | Dispatch to `development/dead-code-graveyard` for access verification and safe deprecation. |113114## Implementation Examples115116### Automated Engineering Dispatcher (Python)117118```python119import sys120from typing import Dict, List, Optional121122class SoftwareEngineerRouter:123 """Deterministic skill dispatcher for Software Engineering tasks."""124 125 DISPATCH_TABLE: Dict[str, str] = {126 "bug_fix": "development/tdd-bug-reproduction",127 "root_cause_unknown": "development/systematic-debugging",128 "concurrency_issue": "development/concurrency-race-audit",129 "contract_mismatch": "development/api-contract-drift-audit",130 "unsafe_types": "development/type-narrowing-audit",131 "dead_code": "development/dead-code-graveyard",132 "pre_merge_review": "development/code-reviewer",133 }134 135 def dispatch(self, issue_type: str, context: Dict[str, str]) -> str:136 skill = self.DISPATCH_TABLE.get(issue_type)137 if not skill:138 raise ValueError(f"Unknown issue type: {issue_type}")139 140 print(f"[ENGINEER ROLE] Dispatching task '{context.get('title')}' -> {skill}")141 return skill142143if __name__ == "__main__":144 router = SoftwareEngineerRouter()145 target_skill = router.dispatch(146 issue_type="bug_fix",147 context={"title": "Fix payment idempotency token race condition"}148 )149 assert target_skill == "development/tdd-bug-reproduction"150 print("Software Engineer dispatcher routing verified.")151```152153### Red-Green-Refactor Verification Script (Bash)154155```bash156#!/usr/bin/env bash157set -euo pipefail158159TEST_FILE="tests/test_regression.py"160echo "=== Step 1: Running Regression Test (Expect Red) ==="161if pytest "$TEST_FILE" -q; then162 echo "ERROR: Test passed before fix! Reproduction invalid."163 exit 1164else165 echo "SUCCESS: Test reproduced failure cleanly."166fi167168echo "=== Step 2: Applying Minimal Fix ==="169# Fix applied here...170171echo "=== Step 3: Re-running Regression Test (Expect Green) ==="172pytest "$TEST_FILE" -q --tb=short173echo "SUCCESS: Fix verified. 100% tests passing."174```175176## Verification Checklist177178- [ ] Problem definition isolated with concrete reproduction trace before code modification.179- [ ] Reproducing test created and verified failing (Red state confirmed).180- [ ] Minimal surgical diff applied to resolve root cause without unrequested abstractions.181- [ ] Sibling files audited to eliminate similar vulnerabilities across the codebase.182- [ ] Full automated test suite passes with zero regressions.183- [ ] Code review completed with empirical execution receipt documented.