Dev Workflow Planning

Workflow Planning Skill - Quick Reference

This skill enables structured, systematic development workflows. The assistant should apply these patterns when users need to break down complex projects, create implementation plans, or execute multi-step development tasks with clear checkpoints.

Inspired by: Obra Superpowers patterns for structured agent workflows.

---

Quick Reference

When to Use This Skill

The assistant should invoke this skill when a user requests:

• Break down a complex feature into steps
• Create an implementation plan
• Brainstorm approaches to a problem
• Execute a multi-step development task
• Track progress on a project
• Review and adjust mid-implementation

---

The Three-Phase Workflow

Phase 1: Brainstorm

Purpose: Explore the problem space and generate potential solutions.

/brainstorm [topic or problem]

OUTPUT:
1. Problem Understanding
   - What are we solving?
   - Who is affected?
   - What are the constraints?

2. Potential Approaches (3-5)
   - Approach A: [description, pros, cons]
   - Approach B: [description, pros, cons]
   - Approach C: [description, pros, cons]

3. Questions to Resolve
   - [List of unknowns needing clarification]

4. Recommended Approach
   - [Selected approach with justification]

Phase 2: Write Plan

Purpose: Create a detailed, actionable implementation plan.

/write-plan [feature or task]

OUTPUT:
## Implementation Plan: [Feature Name]

### Goal
[Single sentence describing the outcome]

### Success Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

### Steps (with estimates)

#### Step 1: [Name] (~Xh)
- What: [specific actions]
- Files: [files to modify/create]
- Dependencies: [what must exist first]
- Verification: [how to confirm done]

### Risks & Mitigations
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| Risk 1 | Medium | High | Plan B if... |

### Open Questions
- [Questions to resolve before starting]

Dependency Graph for Parallel Execution

When a plan will be executed with multiple subagents, each task must declare its dependencies explicitly. This enables the orchestrator to determine which tasks can run in parallel.

### Task Dependency Graph

| Task ID | Name | depends_on | Files | Agent Scope |
|---------|------|------------|-------|-------------|
| T1 | Setup database schema | [] | db/schema.sql | db-engineer |
| T2 | Create API routes | [T1] | src/routes/*.ts | backend-dev |
| T3 | Build auth middleware | [T1] | src/middleware/auth.ts | backend-dev |
| T4 | Frontend components | [] | src/components/*.tsx | frontend-dev |
| T5 | Integration tests | [T2, T3, T4] | tests/integration/*.test.ts | qa-agent |

Rules for dependency graphs:

• Every task declares depends_on: [] with explicit task IDs (empty array = no blockers).
• Tasks with no dependencies can start immediately (in parallel).
• No circular dependencies — the graph must be a DAG (directed acyclic graph).
• Each task should specify its file ownership to prevent parallel conflicts.

Parallel Execution Strategies

Swarm Waves (Accuracy-First) — Launch one subagent per unblocked task, in dependency-respecting waves. Wait for each wave to complete before launching the next. Best for production code and complex interdependencies.

Super Swarms (Speed-First) — Launch as many subagents as possible at once, regardless of dependencies. Best for prototypes and greenfield scaffolding. Expect merge conflicts.

See references/planning-templates.md for the full swarm-ready plan template.

Phase 3: Execute Plan

Purpose: Implement the plan systematically with checkpoints.

/execute-plan [plan reference]

EXECUTION PATTERN:
1. Load the plan
2. For each step:
   a. Announce: "Starting Step X: [name]"
   b. Execute actions
   c. Verify completion
   d. Report: "Step X complete. [brief summary]"
3. After completion:
   a. Run all verification criteria
   b. Report final status

---

Worktree-First Delivery

For production coding sessions, wrap /execute-plan with a delivery guardrail:

1. Create one isolated worktree per feature. 2. Execute only the approved plan scope in that worktree. 3. Run repo-defined quality gate(s) before PR (example: npm run test:analytics-gate). 4. Open one focused PR per feature branch.

./scripts/git/feature-workflow.sh start <feature-slug>
cd .worktrees/<feature-slug>
# implement plan steps
../../scripts/git/feature-workflow.sh gate
../../scripts/git/feature-workflow.sh pr --title "feat: <summary>"

---

Agent Session Management

Key rules from production experience (Feb 2026):

• One feature per session. Context exhaustion causes rework. A sprawling session (38 messages, 3+ continuations) produced multiple errors; a focused session (5 messages) shipped clean.
• Write a plan before touching 3+ files. Sessions with pre-written numbered plans had near-zero rework.
• Verify SDK types before executing plan steps. Documentation may describe APIs that no longer match actual TypeScript definitions.

See references/session-patterns.md for the full production evidence table and checkpoint protocol for long sessions.

---

Command Preflight Protocol

Before broad edits, tests, or reviews — run a 60-second preflight: 1. pwd / git branch --show-current / ls -la 2. test -e <path> to verify target paths before heavy commands 3. npx <tool> --help to validate flags before first use 4. Quote paths containing [], *, ?, or spaces

See references/operational-checklists.md for the full git/branch safety preflight, E2E/server preflight, shell safety gate, and SDK type verification.

---

Structured Patterns

Hypothesis-Driven Development

PATTERN: Test assumptions before committing

Before implementing:
1. State hypothesis: "If we [action], then [expected outcome]"
2. Define experiment: "To test this, we will [minimal test]"
3. Execute experiment
4. Evaluate: "Hypothesis confirmed/rejected because [evidence]"
5. Proceed or pivot based on result

Incremental Implementation

Build in verifiable increments: smallest testable unit → implement and verify → expand scope → verify at each expansion → integrate and verify whole.

See references/planning-templates.md for an authentication feature example with 5 increments.

Progress Tracking

PATTERN: Maintain visible progress

[X] Step 1: Create database schema
[X] Step 2: Implement API endpoints
[IN PROGRESS] Step 3: Add frontend form
[ ] Step 4: Write tests

Current: Step 3 of 4 (75% complete)
Blockers: None
Next: Complete form validation

Work in Progress (WIP) Limits

Limit concurrent work: individual (2-3 tasks), team stories (team size + 1), in-progress column (3-5 items), code review (2-3 PRs). If limits are never reached, lower them. If constantly blocked, investigate the bottleneck.

See references/planning-templates.md for the full WIP limits reference and setting guidelines.

---

Milestone Checkpointing and Scope Budgeting

For multi-step execution, constrain scope and checkpoint progress at milestone boundaries.

• Define explicit session scope at start: 1-2 deliverables only.
• If a new request expands beyond scope, create a follow-up milestone.

Milestone Checkpoint Contract

At each milestone, record:

• completed outputs (files/features/tests)
• verification results (commands + pass/fail)
• unresolved blockers
• next bounded action

Stop Conditions

Stop and rescope when any occur:

• repeated nonzero failures without new evidence
• context churn (re-reading same files repeatedly)
• more than 3 independent domains active in one session

See references/session-scope-budgeting.md for full scope budgeting model and enforcement rules.

---

Session Management

Starting a Session

Session initialized.
- Project: [name]
- Goal: [today's objective]
- Context loaded: [files, previous decisions]
- Plan status: [steps remaining]

Ready to continue from: [last checkpoint]

Ending a Session

/summarize

OUTPUT:
## Session Summary

### Completed
- [List of completed items]

### In Progress
- [Current state of incomplete work]

### Decisions Made
- [Key decisions with rationale]

### Next Session
- [ ] [First task for next time]

### Context to Preserve
[Critical information for continuity]

---

Decision Framework

When faced with choices:

1. State the decision clearly
2. List options (2-4)
3. For each option: Pros / Cons / Effort / Risk
4. Recommendation with justification
5. Reversibility assessment

Example:
| Option | Pros | Cons | Effort | Risk |
|--------|------|------|--------|------|
| JWT | Stateless, scalable | Token management | 2 days | Low |
| Sessions | Simple, secure | Server state | 1 day | Low |
| OAuth only | No passwords | External dependency | 3 days | Medium |

Recommendation: Sessions for MVP, plan JWT migration for scale.

---

Integration with Other Skills

With Testing Skill

/write-plan with TDD:

Step 1: Write failing test
Step 2: Implement minimal code
Step 3: Verify test passes
Step 4: Refactor
Step 5: Add edge case tests

With Architecture Skill

/brainstorm system design:

1. Requirements clarification
2. Component identification
3. Interface definition
4. Data flow mapping
5. Implementation plan

---

Definition of Ready / Done (DoR/DoD)

[assets/template-dor-dod.md](assets/template-dor-dod.md) - Checklists for work readiness and completion.

[assets/template-work-item-ticket.md](assets/template-work-item-ticket.md) - Ticket template with DoR/DoD and testable acceptance criteria.

Key sections: Definition of Ready / Done checklists, Acceptance Criteria templates (Gherkin), Estimation Guidelines (story point scale 1-21+), Planning Levels (Roadmap → Sprint → Task), Cross-Functional RACI.

---

Do / Avoid

GOOD: Do

• Check DoR before pulling work into sprint
• Verify DoD before marking complete
• Size stories using reference scale
• Slice large stories (>8 points)
• Document acceptance criteria upfront
• Include risk buffer in estimates

BAD: Avoid

• Starting work without clear acceptance criteria
• Declaring "done" without testing
• Working on stories too big to finish in sprint
• Skipping code review "to save time"
• Deploying without staging verification

---

Anti-Patterns

---

AI/Automation

Note: AI can assist but should not replace human judgment on priorities and acceptance.

• Generate acceptance criteria - Draft from story description (needs review)
• Suggest story slicing - Based on complexity analysis
• Dependency mapping - Identify blocking relationships
• AI-augmented planning - Use LLMs to draft plans, but validate assumptions

AI-generated criteria and estimates require human calibration before committing to them.

---

Navigation

Resources

• references/planning-templates.md - Plan templates, incremental implementation, WIP limits
• references/session-patterns.md - Multi-session management, production lessons (Feb 2026)
• references/session-scope-budgeting.md - Scope budgeting rules and stop/rescope criteria
• references/operational-checklists.md - Preflight protocols, verification, failure ledger, subagent limits
• references/flow-metrics.md - DORA metrics, WIP limits, flow optimization
• references/agile-ceremony-patterns.md - Sprint ceremonies, retrospectives, facilitation patterns
• references/technical-debt-management.md - Debt classification, prioritization, remediation workflows
• references/remote-async-workflows.md - Async-first patterns, distributed team coordination
• assets/template-dor-dod.md - DoR/DoD checklists, estimation, cross-functional coordination
• assets/template-work-item-ticket.md - Work item ticket template
• assets/template-milestone-checkpoint.md - Milestone checkpoint record
• data/sources.json - Workflow methodology references

Related Skills

• ../software-architecture-design/SKILL.md - System design planning
• ../docs-ai-prd/SKILL.md - Requirements to plan conversion
• ../qa-testing-strategy/SKILL.md - TDD workflow integration
• ../qa-debugging/SKILL.md - Systematic debugging plans

Definition of Ready / Done (DoR/DoD) Templates

Standard checklists for ensuring work items are ready to start and truly complete.

---

Definition of Ready (DoR)

Work items must pass this checklist before being pulled into a sprint/iteration.

User Story DoR Checklist

• [ ] Title: Clear, concise, describes the outcome
• [ ] User story format: "As a [user], I want [goal], so that [benefit]"
• [ ] Acceptance criteria: 3-7 testable conditions defined
• [ ] Sized: Story points or T-shirt size assigned
• [ ] Dependencies: External dependencies identified and unblocked
• [ ] Design: UX/UI mockups available (if applicable)
• [ ] Technical feasibility: Spike completed (if high uncertainty)
• [ ] Testable: QA understands how to verify
• [ ] Small enough: Can be completed in one sprint

Bug DoR Checklist

• [ ] Reproduction steps: Clear steps to reproduce
• [ ] Expected vs actual: Documented behavior difference
• [ ] Environment: Browser, OS, device, version specified
• [ ] Severity: Impact level assigned (Critical/High/Medium/Low)
• [ ] Screenshots/logs: Evidence attached
• [ ] Assignable: Root cause area identified

Technical Task DoR Checklist

• [ ] Scope: Clear boundaries defined
• [ ] Exit criteria: How we know it's done
• [ ] Approach: Technical approach agreed
• [ ] Dependencies: Upstream work complete
• [ ] Reviewable: Someone available to review

---

Definition of Done (DoD)

Work items must pass this checklist before being marked complete.

Feature DoD Checklist

Code Quality

• [ ] Code written and follows style guide
• [ ] Code reviewed and approved
• [ ] No new linter warnings/errors
• [ ] No hardcoded secrets or credentials
• [ ] Error handling implemented

Testing

• [ ] Unit tests written and passing
• [ ] Integration tests passing
• [ ] Edge cases covered
• [ ] No regression in existing tests
• [ ] Manual smoke test completed (if applicable)

Documentation

• [ ] Code comments for complex logic
• [ ] API documentation updated (if applicable)
• [ ] README updated (if applicable)
• [ ] Changelog entry added (if applicable)

Deployment

• [ ] Deployed to staging environment
• [ ] Verified in staging
• [ ] Feature flag configured (if applicable)
• [ ] No breaking changes to API (or versioned)

Acceptance

• [ ] Acceptance criteria verified
• [ ] Product owner accepted
• [ ] No blockers for production release

Bug Fix DoD Checklist

• [ ] Bug no longer reproducible
• [ ] Regression test added
• [ ] Root cause documented
• [ ] Related issues checked
• [ ] Fix reviewed and approved
• [ ] Deployed and verified

Spike DoD Checklist

• [ ] Question answered with evidence
• [ ] Recommendation documented
• [ ] Next steps identified
• [ ] Time box respected
• [ ] Findings shared with team

---

Acceptance Criteria Templates

Format: Given/When/Then (Gherkin)

Feature: User login

  Scenario: Successful login with valid credentials
    Given I am on the login page
    When I enter valid username and password
    And I click the login button
    Then I should be redirected to the dashboard
    And I should see a welcome message

  Scenario: Failed login with invalid password
    Given I am on the login page
    When I enter valid username and invalid password
    And I click the login button
    Then I should see an error message "Invalid credentials"
    And I should remain on the login page

Format: Bullet List

## Acceptance Criteria

- [ ] User can enter email and password
- [ ] Login button is disabled until both fields have values
- [ ] Invalid credentials show error message
- [ ] Successful login redirects to dashboard
- [ ] Session expires after 30 minutes of inactivity
- [ ] "Remember me" extends session to 7 days

Format: Rule-Based

## Acceptance Criteria

**Rule 1: Email validation**
- Email must be valid format
- Email must not be already registered (for signup)
- Error message shown for invalid email

**Rule 2: Password requirements**
- Minimum 8 characters
- At least one uppercase, one lowercase, one number
- Strength indicator updates in real-time

**Rule 3: Rate limiting**
- Max 5 failed attempts per 15 minutes
- Lockout message shown on 6th attempt
- Account unlocks automatically after 15 minutes

---

Estimation Guidelines

Story Point Reference Scale

Slicing Strategies

SPIDR Framework:

• Spike: Reduce uncertainty first
• Paths: Split by user flow variations
• Interfaces: Split by input/output channels
• Data: Split by data types or subsets
• Rules: Split by business rules

Example: Split by Paths

Before: "User can manage their profile"
After:
- User can view their profile
- User can edit their name
- User can change their email (with verification)
- User can upload profile photo
- User can delete their account

Risk Buffers

---

Planning Levels

Roadmap -> Milestone -> Sprint -> Task

Example Hierarchy

Roadmap: Q1 2025 - Improve user onboarding
|-- Milestone: Reduce time-to-value by 50%
|   |-- Epic: Guided setup wizard
|   |   |-- Story: First-time user sees wizard
|   |   |-- Story: User can skip wizard
|   |   `-- Story: Wizard tracks completion
|   `-- Epic: Interactive tutorials
|       |-- Story: Tutorial for core feature
|       `-- Story: Tutorial progress saved
`-- Milestone: Reduce churn in first week
    `-- Epic: Proactive engagement
        |-- Story: Day 2 email with tips
        `-- Story: In-app progress indicators

---

Cross-Functional Coordination

RACI Matrix Template

R = Responsible, A = Accountable, C = Consulted, I = Informed

Handoff Checklist

Design -> Engineering

• [ ] Mockups/wireframes complete
• [ ] Design specs documented
• [ ] Edge cases discussed
• [ ] Assets exported

Engineering -> QA

• [ ] Feature deployed to staging
• [ ] Test data prepared
• [ ] Acceptance criteria clear
• [ ] Known limitations documented

QA -> Product

• [ ] All acceptance criteria verified
• [ ] Test results documented
• [ ] Bugs filed and triaged
• [ ] Sign-off requested

---

Do / Avoid

GOOD: Do

• Check DoR before pulling work
• Verify DoD before marking complete
• Size stories using reference scale
• Slice large stories (>8 points)
• Document acceptance criteria upfront
• Include risk buffer in estimates
• Coordinate handoffs explicitly

BAD: Avoid

• Starting work without clear acceptance criteria
• Declaring "done" without testing
• Estimating without understanding scope
• Working on stories too big to finish in sprint
• Skipping code review "to save time"
• Deploying without staging verification
• Assuming handoffs happen automatically

---

Anti-Patterns

---

Optional: AI/Automation

Note: AI can assist but should not replace human judgment on priorities and acceptance.

AI-Assisted Planning

• Generate acceptance criteria draft from story description
• Suggest story slicing based on complexity analysis
• Identify missing edge cases in requirements

Automation Tools

• JIRA/Linear templates with DoR/DoD checklists
• CI/CD gates that verify DoD items
• Automated test coverage reporting

Bounded Claims

• AI-generated acceptance criteria need human review
• Story point estimates require team calibration
• Dependency mapping suggestions need validation

---

Related Templates

• planning-templates.md - Feature/bug/spike plans
• session-patterns.md - Multi-session workflows

---

Last Updated: December 2025

Template: Milestone Checkpoint

Milestone

• Milestone ID: M-__
• Scope: ___________________________________________
• Date: YYYY-MM-DD
• Owner: ___________________________________________

Completed

• _______________________________________________
• _______________________________________________

Verification Evidence

Blockers / Risks

• _______________________________________________
• _______________________________________________

Scope Drift Check

• New requests outside milestone scope? yes / no
• If yes, deferred milestone ID: M-__

Next Bounded Action

_________________________________________________

Status

• [ ] Milestone complete
• [ ] Follow-up required

Work Item Ticket Template (DoR/DoD + Acceptance Criteria)

Copy-paste into Jira/Linear/GitHub Issues to make work scannable, testable, and releasable.

---

Core

Summary

• Title:
• Type: feature / bug / tech debt / spike
• Owner:
• Priority:
• Milestone/Sprint:
• Stakeholders:

Problem Statement

• What is broken or missing?
• Who is impacted?
• Why now?

Scope

• In scope:
• Out of scope:

Context / Links

• PRD/RFC:
• Designs:
• Logs/metrics:
• Related tickets:

Acceptance Criteria (Required)

Pick one style and keep it testable.

Option A: checklist

• [ ] AC1:
• [ ] AC2:
• [ ] AC3:

Option B: Given/When/Then

Scenario: ...
  Given ...
  When ...
  Then ...

Definition of Ready (Gate to Start)

Use the checklist and don't start until it's satisfied:

• [ ] DoR complete (see assets/template-dor-dod.md)
• [ ] Dependencies identified and unblocked
• [ ] Security/privacy considerations captured (PII/PHI/PCI, auth scope)
• [ ] Operability requirements captured (logging/metrics/tracing, alerts, runbook impact)
• [ ] Rollout strategy chosen (flag, canary, staged)

Definition of Done (Gate to Close)

• [ ] DoD complete (see assets/template-dor-dod.md)
• [ ] Tests added/updated (unit + integration as applicable)
• [ ] Observability updated (dashboards/alerts if needed)
• [ ] Docs updated (public/internal)
• [ ] Rollback plan documented

Implementation Plan (Tasks)

• [ ] Task 1:
• [ ] Task 2:
• [ ] Task 3:

Risks and Mitigations

Validation Plan

• How will we verify in staging?
• What metrics/SLOs are expected to move?
• What is the rollback trigger?

---

Optional: AI/Automation

• Draft acceptance criteria from the problem statement (human-reviewed)
• Suggest task breakdown and dependencies (human-validated)
• Produce a test plan outline and rollout checklist (human-owned)

Bounded Claims

• AI drafts can miss edge cases and operational constraints.
• Priorities and trade-offs require team calibration.

Agile Ceremony Patterns

Operational reference for running effective agile ceremonies — sprint planning, standups, retrospectives, sprint reviews, backlog refinement, and PI planning. Covers facilitation techniques, timeboxing, async alternatives, and anti-patterns.

Freshness anchor: January 2026 — aligned with Scrum Guide 2020, SAFe 6.0, and current remote-first tooling (Linear, Jira, Miro, Notion).

---

Ceremony Quick Reference

---

Sprint Planning

Decision Tree: Planning Approach

Does the team have stable velocity (>3 sprints of data)?
├── YES → Capacity-based planning
│   ├── Calculate capacity: team members × available days × focus factor
│   ├── Pull stories up to capacity from refined backlog
│   └── Commit to sprint goal, not individual stories
└── NO (new team, changing composition)
    └── Goal-based planning
        ├── Define sprint goal first
        ├── Pull minimum stories to achieve goal
        ├── Leave buffer (30-40% of estimated capacity)
        └── Track velocity to calibrate future sprints

Sprint Planning Agenda

Capacity Calculation

Team capacity = Σ (team member available days × focus factor)

Focus factor:
- New team: 0.5-0.6
- Established team: 0.7-0.8
- Experienced team: 0.8-0.85
- Never assume 1.0

Deductions:
- PTO / holidays
- On-call / support rotation
- Company meetings / all-hands
- Onboarding new members (both mentor and mentee)

Sprint Planning Checklist

• [ ] Sprint goal is a single sentence describing the outcome
• [ ] Stories are refined (acceptance criteria exist, estimated)
• [ ] Dependencies on other teams identified and communicated
• [ ] Tech debt allocation included (target 15-20% of capacity)
• [ ] Team members confirmed availability for the sprint
• [ ] No story exceeds 50% of sprint capacity (split if larger)
• [ ] Sprint goal is visible in the team's workspace

---

Daily Standup

Format Options

Walk-the-Board Protocol

1. Open the sprint board
2. Start from the rightmost column (closest to done)
3. For each ticket in progress:
   - Who is working on it?
   - Is it on track to move today?
   - Any blockers?
4. Skip items not started (they are the plan, not the status)
5. Flag anything at risk of not completing this sprint

Async Standup Template

## Daily Update — [Name] — [Date]

**Focus today:**
- [Primary task/ticket]
- [Secondary task if applicable]

**Blockers:**
- [Blocker description] → need [specific help from specific person]

**FYI:**
- [Optional: anything the team should know]

Standup Facilitation Rules

• [ ] Start on time, every time (don't wait for latecomers)
• [ ] Standing / camera-on to maintain energy
• [ ] Timebox individual updates to 2 minutes
• [ ] Parking lot for discussions that need >30 seconds
• [ ] Rotate facilitator weekly (builds ownership)
• [ ] End with: "Who needs help today?"

---

Retrospective

Format Selection Guide

Retrospective Facilitation Agenda

Action Item Rules

• Maximum 3 action items per retro (more won't get done)
• Each action item has a single owner (not "the team")
• Each action item has a due date (default: next retro)
• Review previous retro actions at the start of each retro
• Track completion rate — if <50%, reduce to 1-2 actions

Psychological Safety Checklist

• [ ] Vegas rule stated ("what's said here stays here")
• [ ] Facilitator is NOT the manager (rotate, or use external facilitator)
• [ ] Anonymous input option available (sticky notes, digital cards)
• [ ] No blame language ("the process failed" not "you failed")
• [ ] Manager speaks last (if present at all)
• [ ] Follow through on action items (broken trust kills future retros)

---

Sprint Review / Demo

Sprint Review Agenda

Demo Preparation Checklist

• [ ] Demo environment prepared and tested before the meeting
• [ ] Demo script covers the user flow, not technical implementation
• [ ] Each demo item tied to a user story or sprint goal
• [ ] Backup plan if live demo fails (screenshots, recording)
• [ ] Non-completed items mentioned (transparency, not hidden)
• [ ] Stakeholder questions captured for backlog consideration

---

Backlog Refinement

Refinement Session Structure

Definition of Ready Checklist

• [ ] User story follows format: "As a [who], I want [what], so that [why]"
• [ ] Acceptance criteria are specific and testable
• [ ] Technical approach discussed (no unknown unknowns)
• [ ] Dependencies identified and unblocked (or plan exists)
• [ ] Story sized to complete within one sprint
• [ ] UX designs attached (if applicable)
• [ ] Edge cases documented

Estimation Methods

Estimation Anti-Patterns

• Spending >5 minutes debating 5 vs 8 points — pick the higher one and move on
• Estimating without acceptance criteria — refuse to estimate, send back to PO
• One person dominating estimates — use simultaneous reveal (planning poker)
• Averaging estimates — discuss the gap, understand different assumptions
• Re-estimating completed stories — velocity self-corrects over time

---

PI Planning (SAFe)

PI Planning Agenda (2 Days)

PI Planning Outputs

• [ ] PI objectives for each team (SMART format)
• [ ] Program board showing cross-team dependencies
• [ ] Risks identified with ROAM classification (Resolved, Owned, Accepted, Mitigated)
• [ ] Confidence vote: average ≥3 out of 5 (re-plan if below)
• [ ] Uncommitted objectives clearly marked (stretch goals)

---

Anti-Patterns

---

Cross-References

• dev-workflow-planning/references/technical-debt-management.md — allocating debt work in sprint planning
• dev-workflow-planning/references/remote-async-workflows.md — async alternatives to ceremonies
• startup-hiring-and-management/references/remote-team-management.md — managing distributed agile teams
• qa-testing-strategy/SKILL.md — integrating testing into sprint workflow
• software-architecture-design/SKILL.md — architecture decisions in refinement

Flow Metrics Reference

Delivery performance metrics, WIP limits, and flow optimization patterns.

---

DORA Metrics (5 Keys - 2025 Update)

DORA metrics measure software delivery performance. In 2025, Reliability was added as the 5th metric.

The Five Metrics

Source: DORA 5 Metrics, DORA.dev

Using DORA Metrics

BEST PRACTICES:
1. Measure all 5 metrics together (not in isolation)
2. Use for improvement, not punishment
3. Reduce batch size to improve all metrics
4. Set clear benchmarks against industry standards
5. Cross-functional team ownership of metrics

ANTI-PATTERNS:
- High deployment frequency + high change failure rate
- Low lead time + no reliability monitoring
- Gaming metrics instead of improving process

---

WIP Limits

Work in Progress limits restrict concurrent items in workflow stages.

Why WIP Limits Work

• Makes blockers visible - Can't hide behind "busy"
• Reduces context switching - Focus on completion
• Improves throughput - Encourages finishing before starting
• Shortens cycle time - Items flow faster through the system

Recommended WIP Limits

Setting and Adjusting

INITIAL SETUP:
1. Start with team size + 1
2. Monitor for 2-4 weeks
3. Track where items get stuck

ADJUSTMENT RULES:
- Limits never reached -> Lower them
- Constantly blocked -> Investigate root cause (don't raise limit)
- Frequent exceptions -> Limit too low or process issue

WHEN TO VIOLATE:
- Emergency production fix
- Unblocking critical path
- Always document and review in retro

Source: Atlassian WIP Limits

---

Cycle Time vs Lead Time

LEAD TIME
Request -> Backlog -> In Progress -> Done
   |                      |
   +-- WAIT TIME ---------+-- CYCLE TIME
          Work actively started

Flow Efficiency

Flow Efficiency = (Active Work Time / Total Lead Time) * 100

BENCHMARKS:
- < 15% - Significant waste, lots of waiting
- 15-40% - Typical for most teams
- > 40% - High-performing team

IMPROVEMENT:
1. Reduce WIP to decrease wait time
2. Remove handoff delays
3. Automate repetitive steps
4. Co-locate dependent work

---

Scrumban Hybrid

Combines Scrum's structured planning with Kanban's continuous flow.

When to Use Scrumban

• Mixed work types (features, bugs, urgent requests)
• Need sprint structure but flexible priorities
• Transitioning from Scrum to more flow-based approach

Key Practices

Source: Monday Scrumban Guide

---

Throughput and Predictability

Measuring Throughput

Throughput = Items completed / Time period

TRACKING:
- Stories per sprint
- Bugs fixed per week
- Features shipped per month

USE FOR:
- Forecasting delivery dates
- Capacity planning
- Identifying trends

Monte Carlo Forecasting

Use historical throughput data to predict completion dates:

INPUTS:
- Last 10-20 sprints of throughput data
- Number of items remaining

OUTPUT:
- Probability distribution of completion dates
- "85% confidence: Done by March 15"

BETTER THAN:
- Single-point estimates
- "Gut feel" predictions

---

Quick Reference

DORA Quick Check

Answer these for your team:

1. How often do you deploy? ___ 2. How long from commit to production? ___ 3. What % of deploys cause incidents? ___ 4. How long to recover from incidents? ___ 5. Do you consistently meet SLOs? ___

Compare to DORA benchmarks.

WIP Limit Checklist

• [ ] WIP limits defined for each column
• [ ] Limits visible on board
• [ ] Team agrees on violation policy
• [ ] Blockers escalated immediately
• [ ] Reviewed in retrospectives

Flow Health Indicators

---

Navigation

• Back to SKILL.md
• Planning Templates
• Session Patterns

---

Last Updated: January 2026

Operational Checklists

Pre-flight checks, verification protocols, and failure handling patterns for reliable dev sessions.

---

Command Preflight Protocol

Run this before broad edits, test runs, or multi-file reviews.

60-Second Preflight

1. Confirm context:

• pwd
• git branch --show-current
• ls -la

2. Verify target paths before running heavy commands:

• test -e <path> or rg --files <root> | head
• Prefer discovery first, then exact-path commands.

3. Validate command flags against actual tool version:

• Example: run npx eslint --help before assuming legacy flags like --file.

4. Quote glob-sensitive paths (especially App Router segments):

• Use 'app/src/app/ask/[category]/page.tsx' to avoid shell glob expansion errors.

5. Fail fast on path errors:

• If command reports missing path/pattern, stop and re-derive repository shape before continuing.

Git/Branch Safety Preflight

Run before checkout, merge, and commit:

• git status --porcelain (must be clean or intentionally scoped)
• test -f .git/index.lock && ps aux | rg "[g]it" (lock/process check)
• If switching branches with local changes, commit or stash first.

E2E/Server Preflight

Before Playwright/full E2E:

• Verify target app dir exists (test -d app)
• Verify web server port is free (lsof -i :3001)
• Ensure test file/glob exists before running (rg --files tests/e2e | rg <pattern>)

---

Shell Safety Gate

Run before any file/CLI operation:

1. Path check: test -e <path> (or ls <path>) before sed/cat/rg on a file. 2. Quote dynamic paths and patterns. 3. For multi-pattern ripgrep, always use -e form:

rg -n -e "pattern one" -e "pattern two" <targets>

4. For paths with glob chars ([], *, ?) or spaces, use quoting/escaping.

---

CLI Compatibility Probe

Before first use in a session, run one capability probe and cache syntax for the rest of the task:

npx eslint --help
npx vitest --help
npx tsc --help

Use probed syntax, not assumed flags.

---

Tiered Verification Protocol

Run checks in this order:

1. Edited-file lint/type checks. 2. Feature-scope tests. 3. Full lint/type/build gate once before handoff.

If the same baseline failure repeats unchanged twice, stop re-running broad checks and either:

• narrow scope, or
• record a baseline waiver in the handoff.

---

Failure Ledger

After every failed command, capture:

• Command
• Failure class (path/glob/flag/env/baseline)
• What changed before retry

Do not retry an identical command without changing inputs/environment.

---

Done/Not Done Closure Contract

Every execution summary must end with:

• Done: completed acceptance criteria
• Not done: remaining items/blockers
• Checks run: exact commands run + pass/fail/skip
• Next required action: one concrete next step

---

SDK Type Verification

Plans written from documentation may reference APIs that don't match actual SDK TypeScript types. Before executing a plan step that calls an external SDK, grep the actual TypeScript definitions:

# Example: verify Stripe SDK types before using planned API calls
grep -r "total_count" node_modules/stripe/types/ || echo "NOT FOUND — check actual type"

Common mismatches found in production:

• stripe.customers.list().total_count → SDK has data.length
• invoice.subscription → API changed to invoice.parent.subscription_details.subscription

---

Fan-Out Limits for Subagents

• Max 3 active subagents at once.
• Assign each subagent a file ownership boundary.
• Merge after each batch before spawning new subagents.

Practical Batch Pattern

Batch 1: discovery + plan
Batch 2: implementation in one domain
Batch 3: verification + fixups
Batch 4: handoff summary

Checkpoint Contract (every batch)

Report in one block:

• what changed,
• what was verified,
• what is blocked,
• exact next command.

---

Navigation

• Back to SKILL.md
• Session Scope Budgeting
• Session Patterns

Planning Templates

Copy-paste templates for common planning scenarios.

---

Feature Implementation Plan

## Implementation Plan: [Feature Name]

### Goal
[Single sentence describing the outcome]

### Success Criteria
- [ ] Criterion 1: [Measurable outcome]
- [ ] Criterion 2: [Measurable outcome]
- [ ] Criterion 3: [Measurable outcome]

### Prerequisites
- [ ] [Dependency or setup required before starting]

### Steps

#### Step 1: [Name]
- **What**: [Specific actions to take]
- **Files**: [Files to modify/create]
- **Verification**: [How to confirm done]

#### Step 2: [Name]
- **What**: [Specific actions to take]
- **Files**: [Files to modify/create]
- **Verification**: [How to confirm done]

#### Step 3: [Name]
- **What**: [Specific actions to take]
- **Files**: [Files to modify/create]
- **Verification**: [How to confirm done]

### Risks & Mitigations
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| [Risk 1] | Low/Med/High | Low/Med/High | [Plan B] |

### Open Questions
- [ ] [Question to resolve before/during implementation]

---

Bug Fix Plan

## Bug Fix Plan: [Issue Title]

### Problem Statement
[What's broken and how it manifests]

### Reproduction Steps
1. [Step to reproduce]
2. [Step to reproduce]
3. [Expected vs actual behavior]

### Root Cause Hypothesis
[What you believe is causing the issue]

### Fix Strategy
1. [Approach to fix]
2. [Files to modify]
3. [Testing approach]

### Verification
- [ ] Bug no longer reproducible
- [ ] Existing tests pass
- [ ] New regression test added
- [ ] No side effects observed

---

Refactoring Plan

## Refactoring Plan: [Component/Module]

### Current State
[What exists now and why it's problematic]

### Target State
[What it should look like after refactoring]

### Constraints
- [ ] Must maintain backward compatibility
- [ ] No behavior changes
- [ ] All tests must pass

### Steps (in order of execution)

#### Phase 1: Preparation
- [ ] Add missing test coverage
- [ ] Document current behavior

#### Phase 2: Refactoring
- [ ] [Specific refactoring step]
- [ ] [Specific refactoring step]

#### Phase 3: Verification
- [ ] Run full test suite
- [ ] Manual smoke test
- [ ] Performance comparison

### Rollback Plan
[How to revert if something goes wrong]

---

Spike/Research Plan

## Spike: [Research Topic]

### Question to Answer
[Specific question this spike will answer]

### Time Box
[Maximum time to spend: e.g., 2 hours]

### Success Criteria
- [ ] Question answered with evidence
- [ ] Recommendation documented
- [ ] Next steps identified

### Research Approach
1. [What to investigate first]
2. [What to investigate second]
3. [How to validate findings]

### Output
- Summary of findings
- Recommendation with justification
- Proof of concept (if applicable)

---

Migration Plan

## Migration Plan: [From X to Y]

### Scope
- **Affected systems**: [List]
- **Affected users**: [Count/groups]
- **Data to migrate**: [Type and volume]

### Pre-Migration
- [ ] Backup existing data
- [ ] Notify stakeholders
- [ ] Set up rollback procedure

### Migration Steps
1. [ ] [Step with specific commands/actions]
2. [ ] [Verification checkpoint]
3. [ ] [Next step]

### Post-Migration
- [ ] Verify data integrity
- [ ] Run smoke tests
- [ ] Monitor for errors (24h)

### Rollback Procedure
[Exact steps to revert if needed]

### Communication Plan
| When | What | Who |
|------|------|-----|
| Before | Migration notice | All users |
| During | Status updates | Stakeholders |
| After | Completion notice | All users |

---

Daily/Sprint Planning

## [Date] Planning

### Today's Goal
[One sentence: what success looks like today]

### Priority Tasks
1. [ ] [Highest priority task]
2. [ ] [Second priority]
3. [ ] [Third priority]

### Blockers
- [Any blockers to address first]

### Carry-over from Yesterday
- [Incomplete items from previous session]

### End of Day Checkpoint
- [ ] Goal achieved?
- [ ] What blocked progress?
- [ ] What's first tomorrow?

---

Swarm-Ready Implementation Plan

Use this template when the plan will be executed by multiple parallel subagents.

## Implementation Plan: [Feature Name]

### Goal
[Single sentence describing the outcome]

### Success Criteria
- [ ] Criterion 1: [Measurable outcome]
- [ ] Criterion 2: [Measurable outcome]

### Task Dependency Graph

| Task ID | Name | depends_on | Files (owned) | Agent Role |
|---------|------|------------|----------------|------------|
| T1 | [Task name] | [] | [file paths] | [role] |
| T2 | [Task name] | [T1] | [file paths] | [role] |
| T3 | [Task name] | [] | [file paths] | [role] |
| T4 | [Task name] | [T1, T3] | [file paths] | [role] |

### Execution Strategy
- [ ] **Swarm Waves** (accuracy-first: launch unblocked tasks per wave)
- [ ] **Super Swarms** (speed-first: launch all tasks, resolve conflicts after)

### Task Details

#### T1: [Name]
- **What**: [specific actions]
- **Files to create/modify**: [full paths]
- **Interface contracts**: [what this task exposes for dependent tasks]
- **Acceptance criteria**: [how to verify done]
- **Implementation steps**:
  1. [Step]
  2. [Step]

#### T2: [Name]
- **What**: [specific actions]
- **Depends on**: T1 (needs [specific output/file from T1])
- **Files to create/modify**: [full paths]
- **Acceptance criteria**: [how to verify done]
- **Implementation steps**:
  1. [Step]
  2. [Step]

### Shared Interfaces
[Document any files, types, or contracts that multiple tasks depend on.
Define these before launching parallel work.]

### Conflict Resolution
[If using Super Swarms: which agent's output takes priority for shared files?
What's the merge strategy?]

### Risks & Mitigations
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| Merge conflict on shared types | Medium | Medium | Define interfaces upfront |

---

Incremental Implementation Pattern

Build in verifiable increments — identify the smallest testable unit, implement and verify, then expand scope.

Example — User Authentication feature:

---

WIP Limits Reference

WIP limits restrict maximum items in each workflow stage. Benefits: makes blockers visible, reduces context switching, often increases throughput.

Recommended Limits

Setting WIP Limits

1. Start with team size + 1 2. Monitor for 2-4 weeks 3. If limits never reached → lower them 4. If constantly blocked → investigate bottleneck, don't raise limit 5. Adjust based on actual flow data

When to Violate (thoughtfully)

• Emergency production fix
• Unblocking another team
• Document the exception and review in retro

---

Navigation

• Back to SKILL.md
• Session Patterns

Remote Async-First Workflows

Operational reference for running async-first development workflows — documentation-driven development, RFC/ADR decision processes, async standups, distributed team coordination, meeting minimization, and async retrospectives.

Freshness anchor: January 2026 — aligned with current tooling: Linear, Notion, Loom, Slack workflows, GitHub Discussions, and async-first practices from GitLab, Doist, and Basecamp.

---

Async vs Sync Decision Tree

Does this need to happen in real-time?
├── YES (requires sync)
│   ├── Incident response / live debugging
│   ├── Sensitive feedback (performance reviews, conflict resolution)
│   ├── Complex negotiation with high ambiguity
│   ├── Team bonding / social connection
│   └── Brainstorming requiring rapid iteration (timebox to 30 min)
└── NO (default to async)
    ├── Status updates → Written standup
    ├── Code review → PR comments
    ├── Design decisions → RFC document
    ├── Knowledge sharing → Loom video or written doc
    ├── Sprint planning → Pre-populated board + async review
    ├── Retrospective → Async collection + optional short sync discussion
    └── Announcements → Written post with Q&A thread

Meeting Necessity Checklist

Before scheduling a meeting, verify:

• [ ] Could this be a document? (default: yes)
• [ ] Could this be a Loom video? (for demos, walkthroughs)
• [ ] Could this be a Slack thread? (for quick decisions)
• [ ] Does this require back-and-forth discussion that would take >10 async messages?
• [ ] Are all required participants in overlapping timezone hours?
• [ ] Is the outcome clearly defined (not "discuss X")?

If all answers favor async, do not schedule a meeting.

---

Documentation-Driven Development

Core Principle

Write the document before writing the code. If you can't explain it in writing, you don't understand it well enough to build it.

Document-First Workflow

1. Write the RFC/design doc
   └── Describe: problem, proposed solution, alternatives, risks

2. Share for async review
   └── Set review deadline (48-72 hours)
   └── Tag specific reviewers, not "everyone"

3. Collect feedback
   └── Reviewers comment directly on the document
   └── Author responds to all comments

4. Decide
   └── Author summarizes decision and rationale
   └── Escalate unresolved disagreements to a short sync call

5. Build
   └── Reference the RFC in all related PRs
   └── Update the doc if implementation deviates

6. Archive
   └── Mark as "Implemented" with link to final PR/deployment

RFC (Request for Comments) Template

# RFC: [Title]

**Author:** [name]
**Status:** Draft | In Review | Accepted | Rejected | Implemented
**Created:** 2026-01-15
**Review deadline:** 2026-01-18
**Reviewers:** @person1, @person2, @person3

## Problem Statement
- [1-3 bullet points describing the problem]
- [Quantify impact if possible]

## Proposed Solution
- [Description of the approach]
- [Key design decisions and their rationale]

## Alternatives Considered
| Alternative | Pros | Cons | Why not chosen |
|---|---|---|---|
| [Option A] | [pros] | [cons] | [reason] |
| [Option B] | [pros] | [cons] | [reason] |

## Technical Design
- [Architecture diagram or description]
- [API contracts or data models]
- [Migration plan if applicable]

## Risks and Mitigations
| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| [risk] | [H/M/L] | [H/M/L] | [plan] |

## Rollout Plan
- [ ] Phase 1: [what, when]
- [ ] Phase 2: [what, when]
- [ ] Rollback plan: [how]

## Open Questions
- [ ] [Question 1] — @person to answer
- [ ] [Question 2] — needs investigation

## Decision Log
- [Date]: [Decision made and rationale]

ADR (Architecture Decision Record) Template

# ADR-NNN: [Short title of decision]

**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Date:** 2026-01-15
**Deciders:** [names]

## Context
- [What forces are at play]
- [Why a decision is needed now]

## Decision
- [What we decided]

## Consequences
- [Positive outcomes]
- [Negative outcomes and tradeoffs]
- [Follow-up actions needed]

ADR Management Rules

• [ ] ADRs are numbered sequentially (ADR-001, ADR-002, ...)
• [ ] ADRs are stored in docs/adr/ or docs/decisions/
• [ ] ADRs are never deleted — superseded ADRs link to the replacement
• [ ] ADRs are referenced in related PRs and code comments
• [ ] Quarterly review of recent ADRs to verify decisions still hold

---

Async Standup Patterns

Written Standup (Slack/Linear)

Schedule: Post by team's latest timezone 10:00 AM local time.

## Standup — [Name] — 2026-01-15

**Completed yesterday:**
- [PROJ-123] Finished API endpoint for user search
- Code review on [PROJ-145]

**Focus today:**
- [PROJ-130] Implement pagination for search results
- Pair with @sarah on auth integration (scheduled 2pm UTC)

**Blockers:**
- Waiting on design review for [PROJ-135] — @designer ETA?

**FYI:**
- Out tomorrow afternoon (dentist appointment)

Loom Video Standup

Use when:

• Demonstrating visual work (UI, design, dashboards)
• Explaining complex technical context
• Team prefers face-to-face but timezones prevent it

Format:

• Maximum 3 minutes per person
• Screen share optional (show code, UI, or board)
• Post in dedicated Slack channel with timestamp summary
• Viewers watch at 1.5x speed, comment in thread

Standup Bot Configuration

Async Standup Rules

• [ ] Post window defined (e.g., within first 2 hours of your workday)
• [ ] Blockers get immediate attention (don't wait for someone to read)
• [ ] Tag specific people when you need something from them
• [ ] Link to tickets/PRs rather than describing them
• [ ] Read and react to teammates' standups within 4 hours
• [ ] Weekly summary auto-generated from daily posts

---

Timezone-Distributed Coordination

Overlap Windows Strategy

Team across US Pacific, US Eastern, UK, India:

PST:    06:00 ████████████████████ 22:00
EST:    09:00 ████████████████████ 01:00
GMT:    14:00 ████████████████████ 06:00
IST:    19:30 ████████████████████ 11:30

Overlap (all four): NONE
Overlap (PST+EST+GMT): 14:00-17:00 GMT (06:00-09:00 PST)
Overlap (EST+GMT+IST): 14:00-17:30 GMT (19:30-23:00 IST)

Coordination Patterns by Timezone Gap

Handoff Document Template

## End-of-Day Handoff — [Name] — 2026-01-15

**What I worked on:**
- [PROJ-123] — Status: In Review, PR #456
- [PROJ-130] — Status: Blocked (see below)

**Needs attention from next timezone:**
- PR #456 needs review — context: [brief explanation]
- [PROJ-130] blocked on API response from third-party — if response arrives, proceed with [specific instructions]

**Decisions made today:**
- Chose approach B for caching (see RFC-015 comment thread)

**Don't touch:**
- [PROJ-140] — waiting for design, do not start implementation

Distributed Team Checklist

• [ ] Core hours defined for each timezone pairing (not one global core hour)
• [ ] No meetings outside anyone's 8am-6pm local time
• [ ] Meeting recordings posted with timestamps for key decisions
• [ ] Shared calendar shows each person's working hours
• [ ] Decision-making defaults to async with 48h response window
• [ ] Urgent escalation path defined (and rarely used)

---

Tool Configuration

Communication Layer Map

Slack Configuration for Async

• [ ] Channel naming convention: #team-[name], #proj-[name], #standup-[name]
• [ ] Notification schedule set per timezone (no pings outside work hours)
• [ ] Threads used for all replies (not top-level messages)
• [ ] Important decisions summarized in a pinned message or doc (not buried in Slack)
• [ ] "Do not disturb" hours configured for each timezone
• [ ] Weekly digest of key decisions posted to #team-[name]-decisions

Linear/Jira Async Workflow

• [ ] Ticket status changes trigger Slack notifications to project channel
• [ ] Comments on tickets preferred over Slack for project discussion (searchable, permanent)
• [ ] Sprint board visible to all (no access gatekeeping)
• [ ] Automated weekly velocity/burndown report posted to channel

---

Async Retrospectives

Async Retro Process

Day 1-3: Collection Phase
├── Retro board open (Miro, EasyRetro, Notion)
├── Team members add cards at their own pace
├── Categories: What went well | What didn't | Ideas for improvement
└── Encouraged: 3+ cards per person minimum

Day 4: Voting Phase (async)
├── Each person gets 3-5 votes
├── Vote on cards across all categories
└── Deadline: end of day

Day 5: Discussion + Actions
├── Option A: Short sync call (30 min) to discuss top 3 voted items
├── Option B: Facilitator writes summary, proposes actions in document
│   └── Team has 24h to comment/adjust
└── Output: Max 3 action items with owners and due dates

When to Use Sync vs Async Retro

---

Meeting Minimization Strategies

Meeting Audit Process

1. List all recurring meetings for the team
2. For each meeting, answer:
   ├── What decision or outcome does this produce?
   ├── Could this outcome be achieved async?
   ├── Who actually needs to attend (vs who is invited)?
   └── What is the cost? (attendees × duration × hourly rate)
3. Categorize:
   ├── KEEP: Clear outcome, requires sync, right attendees
   ├── SHORTEN: Outcome ok, but meeting is too long
   ├── CONVERT: Can be done async (document, Loom, Slack)
   └── KILL: No clear outcome, habit meeting
4. Implement changes, review in 4 weeks

Meeting Replacement Patterns

Meeting Rules for Async-First Teams

• [ ] Default meeting length: 25 minutes (not 30), 50 minutes (not 60)
• [ ] Every meeting has an agenda shared 24h in advance
• [ ] No agenda, no meeting (attendees can decline)
• [ ] Meetings produce a written summary within 1 hour (not 1 day)
• [ ] Recordings available for all meetings (async participants)
• [ ] "No meeting" days: Tuesday and Thursday (or team's choice)
• [ ] Meeting-free weeks once per quarter (deep work focus)

---

Anti-Patterns

---

Cross-References

• dev-workflow-planning/references/agile-ceremony-patterns.md — ceremony formats including async variants
• dev-workflow-planning/references/technical-debt-management.md — tracking debt decisions via ADRs
• startup-hiring-and-management/references/remote-team-management.md — broader remote team management
• startup-hiring-and-management/references/culture-and-values-design.md — async culture design
• startup-hiring-and-management/references/founder-delegation-patterns.md — delegation in async environments

Session Patterns

Patterns for managing multi-session projects with a coding assistant.

---

The Session Lifecycle

SESSION START
1. Load context (project memory, previous session notes)
2. Review current plan status
3. Identify today's goal

ACTIVE WORK
- Execute plan steps
- Track progress visibly
- Checkpoint at milestones

SESSION END
1. Summarize completed work
2. Document decisions made
3. Capture context for next session
4. Update project memory if needed

---

Pattern 1: Context Handoff

Problem: The assistant loses context between sessions. How do you maintain continuity?

Solution: Use structured session summaries stored in a project memory file (e.g., CLAUDE.md, AGENTS.md) or a dedicated session-notes.md.

## Session Summary: [Date]

### Completed
- [x] Implemented user authentication API
- [x] Added JWT token generation
- [x] Created login/logout endpoints

### In Progress
- [ ] Frontend login form (50% done, form exists, validation pending)

### Decisions Made
1. Using JWT over sessions for stateless auth
2. Token expiry set to 24 hours
3. Refresh tokens stored in httpOnly cookies

### Blockers
- Need design review for password reset flow

### Next Session: Start Here
1. Complete login form validation
2. Add error handling for auth failures
3. Implement "remember me" checkbox

### Files Modified
- src/auth/jwt.ts (new)
- src/api/routes/auth.ts (new)
- src/middleware/authenticate.ts (new)

---

Pattern 2: Checkpoint Recovery

Problem: Session interrupted mid-task. How do you resume safely?

Solution: Frequent micro-checkpoints during complex work.

/checkpoint [after each significant action]

CHECKPOINT FORMAT:
================
Time: [timestamp]
Last Action: [what was just completed]
Current State: [what exists now]
Next Action: [what comes next]
Rollback Point: [how to undo if needed]
================

Example:
================
Time: 14:32
Last Action: Created database migration for users table
Current State: Migration file exists, not yet applied
Next Action: Run migration, then create User model
Rollback Point: Delete migration file, no DB changes yet
================

---

Pattern 3: Multi-Day Project Tracking

Problem: Large projects span many sessions. How do you track overall progress?

Solution: Maintain a project status file updated each session.

# Project: [Name]

## Overall Progress
Progress: 40% complete

## Milestones
- [x] M1: Project setup and scaffolding (Day 1)
- [x] M2: Database schema and models (Day 2)
- [CURRENT] M3: API endpoints (Day 3-4)
- [ ] M4: Frontend integration (Day 5-6)
- [ ] M5: Testing and polish (Day 7)

## Session Log
| Date | Focus | Outcome |
|------|-------|---------|
| Dec 1 | Setup | Project scaffolded, deps installed |
| Dec 2 | Models | 5 models created, migrations run |
| Dec 3 | API | 3/8 endpoints done |

## Current Sprint
Focus: Complete API endpoints

Tasks:
- [x] GET /users
- [x] POST /users
- [x] GET /users/:id
- [ ] PUT /users/:id
- [ ] DELETE /users/:id
- [ ] GET /posts
- [ ] POST /posts
- [ ] GET /posts/:id

## Blockers Log
| Date | Blocker | Resolution |
|------|---------|------------|
| Dec 2 | DB connection issues | Fixed .env config |

---

Pattern 4: Decision Log

Problem: Forgetting why decisions were made leads to revisiting them.

Solution: Maintain an append-only decision log.

# Decision Log

## DEC-001: Authentication Method
**Date**: 2024-12-01
**Decision**: Use JWT tokens over server-side sessions
**Context**: Building stateless API for mobile app
**Alternatives Considered**:
- Sessions: Simpler but requires sticky sessions
- OAuth only: Too complex for MVP
**Rationale**: JWT allows horizontal scaling, mobile-friendly
**Consequences**: Need token refresh logic, secure storage on client

## DEC-002: Database Choice
**Date**: 2024-12-01
**Decision**: PostgreSQL over MongoDB
**Context**: Relational data with complex queries needed
**Rationale**: Strong consistency, better for financial data
**Consequences**: Need to design schema upfront

## DEC-003: [Next Decision]
...

---

Pattern 5: Context Window Management

Problem: Long sessions fill context window, degrading performance.

Solution: If your platform supports clearing/compacting context, use it intentionally with preserved context.

CONTEXT MANAGEMENT WORKFLOW:

1. Before clearing, extract critical context:
   /summarize -> Save to session-notes.md

2. Clear context:
   /clear

3. Reload essential context:
   "Read project memory and session-notes.md, then continue with [task]"

WHEN TO CLEAR:
- Switching to unrelated task
- After completing major milestone
- When responses slow down
- After ~50+ back-and-forth messages

WHAT TO PRESERVE:
- Current plan and progress
- Recent decisions
- Active file paths
- Uncommitted changes

---

Pattern 6: Parallel Workstreams

Problem: Multiple features in progress simultaneously.

Solution: Track workstreams separately with clear boundaries.

# Active Workstreams

## Workstream A: Authentication
Status: [YELLOW] In Progress (70%)
Branch: feature/auth
Last Updated: Dec 3
Next Action: Implement password reset

## Workstream B: Dashboard UI
Status: [GREEN] Ready for Review
Branch: feature/dashboard
Last Updated: Dec 2
Next Action: Awaiting design approval

## Workstream C: API Rate Limiting
Status: [RED] Blocked
Branch: feature/rate-limit
Blocker: Need Redis setup in staging
Next Action: Wait for DevOps

---

## Today's Focus: Workstream A
[Detailed tasks for current session]

---

Anti-Patterns to Avoid

1. Context Hoarding

Bad: Never clearing context, hoping the assistant remembers everything Good: Regular summarize -> clear -> reload cycles

2. No Checkpoints

Bad: Working for hours without saving progress Good: Checkpoint after each completed step

3. Vague Handoffs

Bad: "Continue where we left off" Good: "Read session-notes.md, we're on Step 3 of the auth implementation"

4. Decision Amnesia

Bad: Rediscussing the same choices each session Good: Reference decision log: "Per DEC-001, we're using JWT"

---

Quick Reference Commands

/session-start [project]  -> Load context, show status
/checkpoint               -> Save current progress
/summarize                -> Generate session summary
/clear                    -> Reset context (after summarize!)
/status                   -> Show project progress

---

---

Lessons from Production (Feb 2026)

Evidence from real coding sessions showing what works and what fails at scale.

Context Exhaustion Is the Dominant Constraint

A single session covering 5 workstreams (i18n, auth, products, retention, docs) ran to 121MB / 33 context continuations. Each continuation lost detail from prior context, causing repeated investigation of known failures, redundant file reads, and solutions contradicting earlier decisions.

Rule: One feature per session. If scope creep appears during execution, checkpoint and start a fresh session for the new scope.

Pre-Written Plans Eliminate Rework

Sessions with pre-written, numbered step plans had near-zero rework:

• Docs actualization (11 steps, 10 files): zero rework, linear execution
• i18n refactor (5 phases, 7 tasks): systematic, minimal rework

Sessions without plans had 1-3 rewrites (e.g., BirthTimeInput: v1 → v2 after UX skill audit).

Rule: For any task touching 3+ files, write a plan first with: 1. Numbered steps with specific file paths 2. Verification criteria per step 3. Dependencies between steps

Checkpoint Protocol for Long Sessions

If a session must span multiple features: 1. After completing each feature, summarize: what changed, what was verified, what's pending 2. Commit completed work before starting next feature 3. If context starts feeling thin (repeating file reads, losing track of changes), start a new session 4. Transfer context via a written summary in the plan file, not by relying on conversation history

Proactive Plan-Doc Reading

Before implementing any feature step: 1. Check if a plan/spec doc exists for the current feature. 2. Read the relevant section of the plan before writing code. 3. Do not rely on user to paste plan context — proactively find and load it.

This prevents building features that contradict the agreed plan or miss requirements documented elsewhere.

---

Navigation

• Back to SKILL.md
• Planning Templates

Session Scope Budgeting

Use this reference to keep long-running execution sessions reliable.

Core Rule

One session should optimize for shipping one bounded outcome, not starting many partially complete streams.

Scope Budget Model

• S: session scope budget (deliverables)
• Default S = 1..2 deliverables
• If incoming tasks exceed S, split into follow-up milestones

Drift Signals

Rescope when you detect:

• repeated re-reading of same files without new decisions
• increasing nonzero command retries without new evidence
• competing priorities across more than 3 domains

Milestone Pattern

1. Discovery + plan 2. Implementation (single domain) 3. Verification + fixups 4. Handoff

Enforcement

At each milestone, produce checkpoint record with:

• done
• blocked
• evidence
• next bounded step

Technical Debt Management

Operational reference for identifying, categorizing, tracking, prioritizing, and systematically reducing technical debt. Covers the debt quadrant model, detection patterns, sprint allocation strategies, and stakeholder communication.

Freshness anchor: January 2026 — aligned with current SonarQube 10.x metrics, CodeClimate, and industry technical debt management practices.

---

Technical Debt Quadrant

Quadrant Decision Guide

Was the debt introduced knowingly?
├── YES (Deliberate)
│   ├── Was there a payback plan?
│   │   ├── YES → Prudent Deliberate (acceptable, track and schedule payback)
│   │   └── NO → Reckless Deliberate (escalate, requires immediate planning)
│   └── Document the tradeoff in ADR
└── NO (Accidental)
    ├── Was the team skilled?
    │   ├── YES → Prudent Accidental (learning-driven, normal, refactor when revisiting)
    │   └── NO → Reckless Accidental (invest in training, pair programming)
    └── Document the discovery and remediation approach

---

Debt Identification Patterns

Code-Level Indicators

Architecture-Level Indicators

Process-Level Indicators

Automated Detection Checklist

• [ ] SonarQube / CodeClimate configured with quality gate
• [ ] Dependency freshness dashboard (Renovate, Dependabot)
• [ ] Test coverage tracked and trending visible
• [ ] CI pipeline duration tracked weekly
• [ ] Code complexity metrics in PR checks
• [ ] Knip / tree-shaking for dead code detection
• [ ] Architecture fitness functions (dependency rules) in CI

---

Tracking Systems

Tagging Approach

Label: tech-debt
Sub-labels:
  - tech-debt/code-quality
  - tech-debt/dependencies
  - tech-debt/testing
  - tech-debt/architecture
  - tech-debt/infrastructure
  - tech-debt/documentation

Priority:
  - P1: Actively causing bugs or incidents
  - P2: Slowing down feature development measurably
  - P3: Will become P2 within 2-3 months
  - P4: Improvement opportunity, no urgency

Tech Debt Ticket Template

## Tech Debt: [Title]

**Category:** [code-quality | dependencies | testing | architecture | infrastructure]
**Quadrant:** [Prudent Deliberate | Reckless Deliberate | Prudent Accidental | Reckless Accidental]
**Priority:** [P1 | P2 | P3 | P4]

### Current State
- What exists today and why it's a problem

### Impact
- How this debt affects velocity / quality / reliability
- Quantify if possible (e.g., "adds 10 min to every deploy")

### Proposed Solution
- What the fix looks like
- Estimated effort: [S | M | L | XL]

### Acceptance Criteria
- [ ] [Specific measurable outcome]
- [ ] [Tests passing, metrics improved, etc.]

### Context
- When was this debt introduced and why
- Link to original ADR/PR if available
- Review date: [date to re-evaluate priority]

ADR (Architecture Decision Record) for Debt

# ADR-NNN: [Decision that creates known debt]

**Status:** Accepted
**Date:** 2026-01-15
**Deciders:** [names]

## Context
[Why we're making this tradeoff]

## Decision
[What we decided to do, knowing it creates debt]

## Debt Created
- [Specific debt item 1]
- [Specific debt item 2]

## Payback Plan
- [When and how we'll address each item]
- Review date: [specific date, max 3 months out]

## Consequences
- Positive: [immediate benefit]
- Negative: [ongoing cost until addressed]

---

Sprint Allocation Strategies

Strategy Comparison

Decision Tree: Choosing a Strategy

How much debt has accumulated?
├── CRITICAL (causing incidents, blocking features)
│   └── Debt Sprint(s) — dedicate full capacity until stable
├── HIGH (measurably slowing velocity)
│   └── 30% allocation until under control, then drop to 20%
├── MODERATE (noticeable but manageable)
│   └── 20% Rule + Boy Scout Rule
└── LOW (well-maintained codebase)
    └── Boy Scout Rule + occasional debt stories

Making the 20% Rule Work

• [ ] Tech debt stories are estimated and planned like feature stories
• [ ] Sprint planning explicitly allocates debt capacity
• [ ] Debt stories have acceptance criteria (not "clean up X")
• [ ] Debt work counts toward velocity (same estimation system)
• [ ] Track debt resolution rate alongside feature delivery
• [ ] If debt allocation is skipped, carry forward (don't lose it)

---

Prioritization Framework

Impact-Effort Matrix for Tech Debt

           High Impact
               │
    ┌──────────┼──────────┐
    │  DO NEXT │ DO FIRST │
    │  (Plan)  │ (Sprint) │
    │          │          │
────┼──────────┼──────────┼────
    │          │          │
    │ CONSIDER │ QUICK WIN│
    │(Backlog) │  (Now)   │
    │          │          │
    └──────────┼──────────┘
               │
           Low Impact
    High Effort          Low Effort

Prioritization Scoring

Urgency Signals (Promote to P1)

• Debt item was root cause in last 2 incidents
• Team velocity dropped >20% and debt is a contributing factor
• Security vulnerability in the debt area
• Regulatory compliance at risk
• Key team member leaving who understands the debt area

---

Stakeholder Communication

Framing Tech Debt for Non-Technical Stakeholders

Debt Health Dashboard

Reporting Cadence

---

Prevention Patterns

Preventing New Debt Accumulation

• [ ] Definition of Done includes code review, tests, and documentation
• [ ] PR template asks: "Does this introduce known technical debt? If yes, link the tracking ticket."
• [ ] Architecture Decision Records (ADRs) required for significant design choices
• [ ] Complexity limits enforced in CI (fail PR if cyclomatic complexity >15)
• [ ] Dependency update automation (Renovate/Dependabot) with auto-merge for patches
• [ ] Quarterly architecture review to catch drift early
• [ ] "Debt introduced" label added to PRs that knowingly add debt

Code Review Debt Gates

During code review, check:
├── New TODO/FIXME comments → Must link to a tracking ticket
├── Copied/pasted code blocks → Must extract to shared module or justify
├── Skipped tests with reason "will add later" → Must link to ticket with due date
├── Workaround for upstream bug → Must link to upstream issue
└── "Quick fix" in incident response → Must link to follow-up cleanup ticket

---

Anti-Patterns

---

Cross-References

• dev-workflow-planning/references/agile-ceremony-patterns.md — allocating debt in sprint planning
• dev-workflow-planning/references/remote-async-workflows.md — async debt tracking and RFC process
• software-clean-code-standard/references/code-complexity-metrics.md — measuring code quality
• qa-refactoring/SKILL.md — refactoring strategies for debt reduction
• qa-refactoring/references/characterization-testing.md — testing legacy code before refactoring
• software-architecture-design/SKILL.md — architecture-level debt decisions