swe-workflow-skills 0.1.0

package/skills/refactoring/references/transformations.md

@@ -0,0 +1,132 @@
+# Safe Refactoring Transformations
+
+## Contents
+- Extract transformations
+- Move transformations
+- Simplify transformations
+- Rename transformations
+- Data transformations
+
+## Extract Transformations
+
+### Extract Method
+**When**: A code block does a distinct subtask within a larger function.
+**How**: Move the block to a new function. Pass needed values as parameters. Return what the caller needs.
+**Watch for**: Don't extract if it requires more than 3 parameters — that signals the function is entangled with too much state.
+
+### Extract Variable
+**When**: A complex expression is hard to read.
+**How**: Assign the expression to a well-named local variable.
+**Watch for**: Don't create variables for trivially simple expressions.
+
+### Extract Class
+**When**: A class has fields/methods that form a natural cluster separate from the rest.
+**How**: Move the cluster to a new class. The original class delegates to the new one.
+**Watch for**: Don't extract if the "cluster" is just one method — that's probably Extract Method.
+
+### Extract Interface/Protocol
+**When**: Multiple classes share a subset of methods that consumers depend on.
+**How**: Define the shared contract explicitly. Depend on the abstraction.
+**Watch for**: YAGNI — don't extract an interface with only one implementation unless you need it for testing.
+
+## Move Transformations
+
+### Move Method
+**When**: A method uses more data from another class than its own (feature envy).
+**How**: Move it to the class whose data it uses most. The original method becomes a delegating call or is removed.
+
+### Move Field
+**When**: A field is used more by another class than by its owner.
+**How**: Move it and update all references.
+
+### Inline Method
+**When**: A method's body is as clear as its name, or the method is only called once and adds no abstraction value.
+**How**: Replace the call with the method body. Remove the method.
+
+## Simplify Transformations
+
+### Replace Conditional with Early Return
+**When**: Deep nesting from null checks or validation.
+**Before**: `if (x) { if (y) { if (z) { doThing() } } }`
+**After**: `if (!x) return; if (!y) return; if (!z) return; doThing()`
+
+### Replace Conditional with Polymorphism
+**When**: Switch/if-else chains that select behavior based on type.
+**How**: Each case becomes a class implementing a shared interface.
+**Watch for**: Only worthwhile if the switch appears in multiple places.
+
+### Decompose Conditional
+**When**: A complex boolean expression controls flow.
+**How**: Extract each part into a well-named method: `isEligible()` instead of `age > 18 && hasId && !isBanned`.
+
+### Replace Magic Number with Named Constant
+**When**: A literal value has domain meaning.
+**How**: Extract to a constant with a descriptive name.
+
+### Consolidate Duplicate Conditional Fragments
+**When**: The same code appears in every branch of a conditional.
+**How**: Move it outside the conditional.
+
+## Rename Transformations
+
+### Rename Variable/Function/Class
+**When**: The name doesn't reveal intent or uses abbreviations.
+**Rules**:
+- Functions: verb phrases (`calculateTotal`, `sendNotification`)
+- Variables: noun phrases describing the value (`activeUserCount`, not `n`)
+- Booleans: question phrases (`isValid`, `hasPermission`, `canEdit`)
+- Classes: noun phrases for the concept (`OrderProcessor`, not `OrderHelper`)
+
+## Data Transformations
+
+### Introduce Parameter Object
+**When**: A function takes 4+ parameters that travel together.
+**How**: Group them into a named object/struct/dataclass.
+**Benefit**: Reduces function signatures and provides a home for related logic.
+
+### Replace Data Value with Object
+**When**: A primitive (string, number) carries domain meaning (email, money, coordinates).
+**How**: Wrap in a domain type with validation and formatting.
+
+### Encapsulate Collection
+**When**: A class exposes a mutable collection directly.
+**How**: Return a copy or provide add/remove/query methods instead.
+
+## Extended Code Smells
+
+These complement the primary smells listed in SKILL.md Step 2. Each is a signal, not a hard rule — context determines whether the smell warrants action.
+
+### Data Clumps
+**Smell**: The same group of fields appears together in multiple function signatures or classes (e.g., `street, city, state, zip`).
+**Fix**: Introduce a parameter object or value type (`Address`) that groups them.
+**Why**: Scattered groups indicate a missing concept in the domain model. Extracting it provides a home for related validation and behavior.
+
+### Speculative Generality
+**Smell**: Abstract classes, interfaces, or parameters that exist "in case we need them later" but have only one implementation or caller.
+**Fix**: Remove the unused abstraction. Reinstate it when a second use case actually appears.
+**Why**: Unused abstractions add indirection that confuses readers and increases maintenance cost for zero benefit.
+
+### Temporary Fields
+**Smell**: Instance variables that are only set and used in certain code paths, leaving them null/undefined the rest of the time.
+**Fix**: Extract the fields and the methods that use them into a separate class, or pass them as method parameters instead of storing as state.
+**Why**: Readers expect instance variables to be meaningful throughout the object's lifetime. Fields that are sometimes null create confusion and null-check clutter.
+
+### Middle Man
+**Smell**: A class where most methods just delegate to another object without adding logic.
+**Fix**: Inline the delegator — have callers use the target class directly. Keep the middle man only if it provides a meaningful abstraction boundary.
+**Why**: Unnecessary delegation adds a layer of indirection that makes code harder to trace without providing value.
+
+### Data Classes
+**Smell**: A class that has only fields and getters/setters with no behavior. Other classes reach in to read its data and perform logic on it (feature envy from the outside).
+**Fix**: Push behavior into the data class. If callers compute derived values from its fields, those computations belong on the class itself.
+**Why**: Data classes violate encapsulation — the logic that belongs with the data is scattered across the codebase.
+
+### Inappropriate Intimacy
+**Smell**: Two classes that know too much about each other's internals — accessing private fields, calling internal methods, or passing internal data structures back and forth.
+**Fix**: Move methods or fields to reduce the coupling. Extract a shared interface if both classes need a common contract. Consider merging if the classes are inseparable.
+**Why**: Intimate coupling means changes to one class ripple unpredictably into the other.
+
+### Comments as Deodorant
+**Smell**: A block comment explaining what a complex piece of code does — not *why*, but *what*. The comment exists because the code is too convoluted to understand on its own.
+**Fix**: Refactor the code so the comment becomes unnecessary. Extract methods with descriptive names, rename variables, simplify conditionals.
+**Why**: The comment is masking a readability problem. If the code changes and the comment doesn't, it becomes a lie. Self-documenting code is more reliable than commented code.

package/skills/retrospective/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: retrospective
+description: "Facilitate sprint retros, project post-mortems, and incident post-mortems with actionable, owned improvements. Triggers: retrospective, retro, post-mortem, postmortem, lessons learned, what went wrong, what went well, incident review, blameless, action items, sprint review, after action review."
+model: haiku
+allowed-tools: Read, Grep, Glob, Write, Edit
+---
+
+# Retrospective
+
+Facilitate structured reflection that produces concrete improvements. The goal is not to assign blame — it's to make the next iteration better than the last.
+
+## Three Formats
+
+### Sprint Retrospective
+**When**: End of every sprint
+**Duration**: 30-60 minutes
+**Scope**: What happened this sprint
+**Output**: 2-3 action items with owners for next sprint
+
+### Project Post-Mortem
+**When**: After a significant project or milestone completes
+**Duration**: 60-90 minutes
+**Scope**: The entire project from planning through delivery
+**Output**: Written document with learnings and recommendations
+
+### Incident Post-Mortem
+**When**: After any production incident that impacted users
+**Duration**: 60 minutes
+**Scope**: The incident timeline, response, and systemic causes
+**Output**: Blameless post-mortem document with prevention actions
+
+## Workflow: Sprint Retrospective
+
+### Step 1: Gather Data
+
+Collect information about the sprint before the meeting:
+- Sprint velocity vs commitment
+- Items completed vs carried over
+- Incidents or bugs discovered
+- Team sentiment (optional pulse survey)
+
+### Step 2: Facilitate Discussion
+
+Use one of these formats:
+
+**Start/Stop/Continue:**
+- **Start doing**: What should we begin doing that we aren't?
+- **Stop doing**: What's wasting time or causing problems?
+- **Continue doing**: What's working well?
+
+**Went Well / Didn't Go Well / Action Items:**
+- What went well this sprint? (Celebrate wins)
+- What didn't go well? (Identify problems without blame)
+- What specific actions will we take to improve?
+
+**4Ls (Liked, Learned, Lacked, Longed for):**
+- What did we like about this sprint?
+- What did we learn?
+- What was lacking?
+- What did we long for (wish we had)?
+
+### Step 3: Prioritize Action Items
+
+Don't try to fix everything. Pick the top 2-3 improvements:
+- Each action item gets an owner (one person, not "the team")
+- Each action item gets a deadline (usually "by end of next sprint")
+- Each action item is specific enough to verify completion
+
+### Step 4: Record and Follow Up
+
+Save the retro notes. At the start of next sprint's retro, review the previous action items: were they completed?
+
+## Workflow: Project Post-Mortem
+
+### Step 1: Prepare the Review
+
+Before the meeting, gather:
+- Original project proposal, PRD, and estimates
+- Actual timeline and effort vs estimated
+- Key decisions made during the project and their outcomes
+- Metrics: did the project hit its success criteria?
+
+### Step 2: Walk Through Key Questions
+
+1. **Did we solve the right problem?** Was the original problem statement accurate?
+2. **Did we estimate well?** Where were estimates off and why?
+3. **What decisions would we make differently?** (Technical, scope, team)
+4. **What processes helped?** (What to keep)
+5. **What processes hindered?** (What to change)
+6. **What surprised us?** (Unknowns that became knowns too late)
+
+### Step 3: Produce the Document
+
+Use the template at [templates/post-mortem.md](templates/post-mortem.md). Share with the team and stakeholders.
+
+## Workflow: Incident Post-Mortem
+
+### Blameless Culture
+
+The most important principle: **incidents are caused by systems, not people.** If a human made an error, the question is "why did the system allow that error to cause an outage?" not "who messed up?"
+
+### Step 1: Build the Timeline
+
+Reconstruct a minute-by-minute timeline:
+- When did the incident start?
+- When was it detected? (By monitoring or by users?)
+- When was the team alerted?
+- What actions were taken and when?
+- When was the incident resolved?
+- When was the root cause confirmed?
+
+### Step 2: Identify Root Causes
+
+Use the "5 Whys" technique to dig past symptoms:
+
+```
+Why did users see errors? → The API returned 500s.
+Why did the API return 500s? → Database connections were exhausted.
+Why were connections exhausted? → A query was holding connections open.
+Why was a query holding connections? → A missing index caused full table scans.
+Why was the index missing? → No index review process exists for migrations.
+→ Root cause: No systematic review of database performance for new migrations.
+```
+
+### Step 3: Define Prevention Actions
+
+For each root cause, define an action that prevents recurrence:
+
+| Action | Type | Owner | Deadline |
+|--------|------|-------|----------|
+| Add EXPLAIN ANALYZE check to migration CI | Prevention | [Name] | [Date] |
+| Add connection pool monitoring alert | Detection | [Name] | [Date] |
+| Document index guidelines for team | Process | [Name] | [Date] |
+
+**Action types:**
+- **Prevention**: Makes the incident impossible to recur
+- **Detection**: Makes the incident detectable before user impact
+- **Mitigation**: Reduces the blast radius if it happens again
+- **Process**: Changes how the team works to reduce risk
+
+### Step 4: Produce the Post-Mortem
+
+Use the template at [templates/post-mortem.md](templates/post-mortem.md). Publish internally — transparency builds trust and helps other teams learn.
+
+## Principles Applied
+
+- **Blameless over blame**: Focus on systems, not individuals. "The deploy script didn't validate X" not "Dave forgot to check X."
+- **Action over discussion**: Every retro must produce specific, owned action items. A retro without action items is just venting.
+- **KISS**: 2-3 action items per retro, not 15. Fewer items done beats many items forgotten.
+- **Continuous improvement**: Small improvements every sprint compound. A 5% improvement per sprint is 3x better in a year.
+
+## Cross-Skill References
+
+- `incident-response` — triggers a post-mortem; use this skill for the post-mortem workflow
+- `technical-debt-review` — if retrospectives repeatedly surface the same maintenance pain, escalate to a full debt review
+
+See [references/facilitation-guide.md](references/facilitation-guide.md) for retro formats, handling difficult conversations, and action item quality criteria.

package/skills/retrospective/evals/evals.json

@@ -0,0 +1,34 @@
+{
+  "skill_name": "retrospective",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We just had a production outage — our payment service was down for 45 minutes because a database migration locked a table. 200 users couldn't complete checkouts. Help me write the post-mortem.",
+      "expected_output": "Should produce a blameless incident post-mortem with timeline, root cause analysis (5 Whys), and prevention action items.",
+      "assertions": [
+        "Uses blameless language throughout (systems, not people)",
+        "Reconstructs a timeline with key events",
+        "Applies 5 Whys to get past 'migration locked table' to systemic cause",
+        "Identifies root cause as missing migration safety process, not the specific migration",
+        "Action items include prevention, detection, AND process improvements",
+        "Each action item has a specific owner and deadline",
+        "Includes 'what went well' section (not just what went wrong)",
+        "Quantifies impact (200 users, 45 minutes, potential revenue loss)"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Run a sprint retrospective for our team. This sprint we completed 8 of 10 planned stories, had one carry-over from last sprint, and our CI pipeline was broken for 2 days due to a flaky test. Team morale seems a bit low.",
+      "expected_output": "Should facilitate a structured retro using Start/Stop/Continue or similar format, address the specific issues (carry-over, CI, morale), and produce 2-3 actionable items.",
+      "assertions": [
+        "Uses a structured format (Start/Stop/Continue, 4Ls, or similar)",
+        "Addresses the CI breakage specifically (not just generically)",
+        "Addresses carry-over pattern (is this recurring?)",
+        "Acknowledges morale concern constructively",
+        "Produces exactly 2-3 action items (not 10)",
+        "Each action item has an owner",
+        "Includes review of previous retro action items"
+      ]
+    }
+  ]
+}

package/skills/retrospective/references/facilitation-guide.md

@@ -0,0 +1,130 @@
+# Retrospective Facilitation Guide
+
+## Choosing the Right Format
+
+| Format | Best for | Duration | Energy level needed |
+|--------|----------|----------|---------------------|
+| Start/Stop/Continue | Regular sprint retros, established teams | 45 min | Low |
+| 4Ls (Liked/Learned/Lacked/Longed for) | Teams that want to celebrate learning | 60 min | Medium |
+| Sailboat | Teams stuck in a rut, need fresh perspective | 60 min | Medium |
+| Timeline | Post-mortems, retrospecting on a long project | 90 min | High |
+| DAKI (Drop/Add/Keep/Improve) | Retros focused on process improvement | 60 min | Medium |
+
+---
+
+## Format Details
+
+### Sailboat
+
+Draw a boat with:
+- **Wind** (pushing us forward): What helped us move fast?
+- **Anchors** (slowing us down): What slowed us down or held us back?
+- **Rocks ahead** (risks): What might cause problems next sprint?
+- **Sun/island** (destination): What's our goal or ideal state?
+
+Works well for teams that have been doing Start/Stop/Continue for too long and need a fresh frame.
+
+### 4Ls
+
+- **Liked**: What did you enjoy or appreciate?
+- **Learned**: What did you discover or understand better?
+- **Lacked**: What was missing that would have helped?
+- **Longed for**: What do you wish existed or had happened?
+
+Good for teams that focus too much on problems — this format forces recognition of positives and learning.
+
+### DAKI
+
+- **Drop**: What should we stop doing entirely?
+- **Add**: What new practice should we start?
+- **Keep**: What's working well that we should protect?
+- **Improve**: What's partially working that we should refine?
+
+More action-oriented than Start/Stop/Continue. Useful when "stop doing X" conversations have been unproductive.
+
+---
+
+## Facilitation Techniques
+
+### Silent brainstorming first
+
+Before group discussion, have each person write items on sticky notes (or a virtual board) silently for 5 minutes. This:
+- Prevents groupthink (early speakers don't anchor the group)
+- Gives quieter team members equal voice
+- Produces more diverse observations
+
+Group similar items by theme before discussing. This keeps discussion focused.
+
+### Dot voting for prioritization
+
+After brainstorming, give each person 3-5 votes to allocate across items. They can put multiple votes on a single item if they feel strongly. Items with the most votes become the action item candidates.
+
+This avoids long debates about prioritization — the votes speak for themselves.
+
+### Timeboxing discussions
+
+Announce timeboxes before discussion starts: "We have 10 minutes for this topic." Visible timers help. When time is up, call for action items or explicitly decide to defer.
+
+Without timeboxes, retros consistently over-run and end without action items.
+
+---
+
+## Handling Difficult Conversations
+
+### When blame starts creeping in
+
+Redirect with process questions: "What made it easy for that to happen?" or "What would have made it impossible?" This shifts from "Dave deployed bad code" to "our process allowed unreviewed code to reach production."
+
+If blame persists: "Let's focus on what we'll do differently, not what was done wrong. What change would prevent this from happening again?"
+
+### When the same issues recur every sprint
+
+Two possibilities: the action items weren't done, or they were done but didn't solve the root cause.
+
+For action items not done: "We committed to X last sprint. It didn't happen — why? Is this actually important? If yes, what needs to change to make it happen?"
+
+For recurring issues after attempted fixes: Use 5 Whys to dig deeper. The real root cause may be one level below what was addressed.
+
+### When a senior person dominates
+
+Structure prevents domination more reliably than asking people to hold back. Silent brainstorming first (see above) equalizes input. Go-around techniques ("let's hear from everyone in turn on this") give quieter voices explicit space.
+
+### When there's nothing to discuss
+
+Low-energy or "everything was fine" retros usually mean one of:
+- The team is burned out and needs a shorter session
+- Trust hasn't been established for candor
+- The sprint genuinely went well (celebrate it!)
+
+For trust issues: Build psychological safety over time by modeling vulnerability: "I'll go first — something I struggled with this sprint was..."
+
+### When a retro produces only complaints with no solutions
+
+Require the action item proposal to come from the same person who raised the issue: "You raised this — what one specific thing could we do next sprint to improve it?" This is uncomfortable but effective. Venting without ownership produces nothing.
+
+---
+
+## Action Item Quality
+
+Good action items:
+- One owner (a named person, not "the team" or "someone")
+- Specific and verifiable ("Add linting to CI by Friday" not "improve code quality")
+- Realistic for one sprint
+- Tracked: reviewed at the start of the next retro
+
+Bad action items:
+- "Be more careful with deployments" — not specific or verifiable
+- "Team to improve test coverage" — no single owner, not measurable
+- "Discuss X next sprint" — a meeting is not an improvement
+
+If you can't make an action item specific and owned, it's not ready to commit to. Either refine it or drop it.
+
+---
+
+## Following Up on Previous Action Items
+
+Always start the retro by reviewing last sprint's action items:
+- "Was X completed? What was the outcome?"
+- If not completed: "Was this actually important? If yes, carry it forward. If no, drop it."
+
+Teams that never review previous action items learn that the retro produces no real change and stop engaging honestly.

package/skills/retrospective/templates/post-mortem.md

@@ -0,0 +1,121 @@
+# Post-Mortem Templates
+
+## Incident Post-Mortem
+
+```markdown
+# Incident Post-Mortem: [Incident Title]
+
+**Date**: [YYYY-MM-DD]
+**Severity**: SEV-1 / SEV-2 / SEV-3
+**Duration**: [X hours Y minutes]
+**Author**: [Name]
+**Status**: Draft | In Review | Final
+
+## Summary
+
+[2-3 sentences: What happened, what was the user impact, how long it lasted.]
+
+## Impact
+
+- **Users affected**: [Number or percentage]
+- **Revenue impact**: [If applicable]
+- **Data impact**: [Any data loss or corruption]
+- **Duration**: [Start time → Detection time → Resolution time]
+
+## Timeline (all times UTC)
+
+| Time | Event |
+|------|-------|
+| HH:MM | [First signs of the problem] |
+| HH:MM | [Alert fired / User report received] |
+| HH:MM | [On-call engineer paged] |
+| HH:MM | [Root cause identified] |
+| HH:MM | [Fix deployed] |
+| HH:MM | [Service fully recovered] |
+
+**Time to detect**: [How long from start to detection]
+**Time to resolve**: [How long from detection to resolution]
+
+## Root Cause
+
+[Detailed explanation of what caused the incident. Use 5 Whys if helpful.
+Be specific and technical. This section should help someone prevent the same issue.]
+
+## What Went Well
+
+- [Effective response actions]
+- [Monitoring that helped]
+- [Team coordination that worked]
+
+## What Went Poorly
+
+- [Detection gaps]
+- [Response delays]
+- [Missing runbooks or documentation]
+
+## Action Items
+
+| Action | Type | Owner | Deadline | Status |
+|--------|------|-------|----------|--------|
+| [Specific action] | Prevention | [Name] | [Date] | ⬜ |
+| [Specific action] | Detection | [Name] | [Date] | ⬜ |
+| [Specific action] | Process | [Name] | [Date] | ⬜ |
+
+## Lessons Learned
+
+[Key takeaways that apply beyond this specific incident.]
+```
+
+## Project Post-Mortem
+
+```markdown
+# Project Post-Mortem: [Project Name]
+
+**Date**: [YYYY-MM-DD]
+**Author**: [Name]
+**Project duration**: [Start → End]
+**Team**: [Names/roles]
+
+## Project Summary
+
+[What the project set out to do and what it actually delivered.]
+
+## Results vs Goals
+
+| Goal | Target | Actual | Met? |
+|------|--------|--------|------|
+| [Goal 1] | [Target] | [Result] | ✅/❌ |
+| [Goal 2] | [Target] | [Result] | ✅/❌ |
+
+## Estimates vs Actuals
+
+| | Estimated | Actual | Delta |
+|---|----------|--------|-------|
+| Duration | [X weeks] | [Y weeks] | [+/- N weeks] |
+| Effort | [X person-weeks] | [Y person-weeks] | [+/- N] |
+| Scope | [N features] | [M features] | [Added/cut] |
+
+## What Went Well
+
+- [Process, decision, or practice that helped]
+- [Technical approach that paid off]
+- [Team dynamic that worked]
+
+## What Could Be Improved
+
+- [Process gap or friction point]
+- [Decision that didn't work out and why]
+- [Estimation miss and what caused it]
+
+## Key Decisions and Their Outcomes
+
+| Decision | Why We Made It | Outcome | Would We Do It Again? |
+|----------|---------------|---------|----------------------|
+| [Decision] | [Rationale] | [Result] | Yes/No/Modified |
+
+## Recommendations
+
+1. [Specific recommendation for future projects]
+2. [Specific recommendation]
+3. [Specific recommendation]
+```