Engineering Playbook

A set of commands and guides for structuring development workflows, architectural decisions, code reviews, and team operations.

Built on two complementary frameworks:

1. The Preamble - How teams think together (peer collaboration, correctness over agreement)
2. Design Rules - What teams build toward (clarity, simplicity, resilience, extensibility)

Every command in the playbook assumes both. Every workflow integrates both.

Start Here

Want the thinking, not the commands? Read The Playbook - five chapters on how teams think together, what they build toward, and how to adopt it. About thirty minutes cover to cover.

New to the playbook? Read Why We Build Playbooks for the full philosophy, or jump to Getting Started for a scenario-based introduction.

Looking for a specific command? Browse the sidebar by category, or use search (press S).

Adopting for your team? See the Adoption Guide for team-size-specific paths.

Not using Claude Code? See Using With Other Tools for adaptation guides.

How It Works

The playbook provides a three-step daily ritual:

scope → code → review

Scope captures what you’re building. You code without interruptions. Review checks your work against relevant quality perspectives and commits when it passes.

Beyond the daily ritual, the playbook includes planning tools, architecture patterns, multi-perspective review workflows, deployment guides, incident response, and team operations.

See Workflows for the full picture, or Recipes for real-world examples.

Browse by Category

Use the sidebar to explore commands organized by workflow sequence within each category: Core, Development, Planning, Reviews, Deployment, Repo, Templates, Utilities, and People.

The Integration Guide shows how commands compose into workflows.

Engineering Playbook: A Complete Philosophy for High-Performance Teams

Introduction

Every engineering team faces the same challenges: preventing regressions, maintaining code quality across a growing codebase, onboarding new team members, responding to incidents, and shipping features without burning out. These are solved problems. Yet most teams reinvent the solutions over and over-in slightly different ways, each time losing efficiency.

The Engineering Playbook is a complete decision framework grounded in two complementary philosophies:

1. The Preamble - How teams think together (peer collaboration, psychological safety, correctness over agreement)
2. Design Rules - What teams build (clarity, simplicity, robustness, extensibility)

It’s not a tool; it’s a set of repeatable processes that work together to make quality the default, not something that requires heroic effort. The playbook codifies both how to think as a team and how to build systems well.

The Problem We’re Solving

Development teams typically struggle with:

Quality Variability - Code review rigor depends on who’s reviewing. Some PRs get deep scrutiny; others barely get looked at. Testing practices differ by project. Standards aren’t documented, so they’re inconsistently applied.

Context Loss - Architectural decisions get made in Slack and forgotten. Six months later, someone asks “why did we design it this way?” and nobody remembers. New team members don’t understand the reasoning behind major decisions.

Incident Chaos - When production breaks, the response depends on who’s on call. There’s no standard assessment process, no documented playbooks for different severity levels, no postmortem template. Teams repeat the same mistakes.

Onboarding Friction - New team members spend weeks or months learning unwritten cultural norms. “Here’s how we do code review.” “Here’s how we do releases.” “Here’s the definition of done.” All spoken, never documented.

Distributed Team Challenges - Async teams struggle with alignment. Standups don’t work. Knowledge stays siloed. Reviews get blocked waiting for timezone-appropriate feedback.

Knowledge Silos - When key people leave, they take institutional knowledge with them. There’s no systematic knowledge transfer process.

These problems aren’t unique to your team. They’re solved problems. The playbook gives you the solution, ready to adapt to your context.

Why Existing Approaches Fall Short

Many teams try to solve these with:

Heavy processes - Mandatory meetings, extensive checklists, extensive documentation that nobody maintains. These reduce agility instead of improving quality.

Light processes - “Just use your judgment” and “communicate well.” This works for 5-person teams but breaks down at scale. Without documentation, standards drift. New team members get inconsistent guidance.

Off-the-shelf frameworks - Scrum, Kanban, SAFe. These address how to organize work, not how to execute it well. They don’t cover code quality, architectural decisions, incident response, or knowledge transfer.

Tool-based solutions - PR checklist bots, automated testing, linters. These catch some issues but can’t replace judgment. They also create false confidence: “tests passed, so we’re good,” when actually test coverage is incomplete.

The playbook bridges this gap. It’s a structured framework that enforces quality gates but remains flexible enough to adapt to your team’s needs. It’s documented so knowledge isn’t lost. It’s integrated so all the pieces work together as a system, not isolated commands.

The Playbook Philosophy: Two Complementary Frameworks

The playbook is built on a unique insight: Quality comes from HOW teams think together AND WHAT they build.

The Two Frameworks Work Together

WITHOUT THE PREAMBLE: Teams apply design rules but debate endlessly about “correctness” without reaching decisions. Status matters more than ideas. Disagreement creates conflict instead of better code.

WITHOUT DESIGN RULES: Teams collaborate well but build systems that are hard to maintain, overly complex, or fragile. Good intentions don’t prevent architectural mistakes or performance problems.

WITH BOTH: Teams collaboratively decide on technically sound systems. Peer thinking enables open discussion of trade-offs. Design rules give concrete language for critiquing ideas. The result: faster decisions, better systems, psychological safety with technical excellence.

The Preamble: How Teams Think Together

The Preamble establishes four core principles about collaboration:

1. Correctness Over Agreement - Find the right answer, don’t defer to authority
2. Critical, Not Servile - Challenge ideas professionally, surface problems early
3. Truth Over Tone - Direct feedback beats careful politeness
4. Think Holistically - Optimize for team outcomes, not individual concerns

In practice: Code reviewers surface flaws, not just approve. Architecture decisions are documented so they can be intelligently challenged. Disagreement is professional. Silence is viewed as complicity. Failures become learning.

Design Rules: What We Build

Design Rules are 17 classical principles organized into 4 clusters:

1. CLARITY - Systems are obviously correct; interfaces are unsurprising

   • Clarity, Least Surprise, Silence, Representation

2. SIMPLICITY - Elegant design with complexity only where justified

   • Simplicity, Parsimony, Separation, Composition

3. RESILIENCE - Reliable systems that fail loudly and recover well

   • Robustness, Repair, Diversity, Optimization

4. EXTENSIBILITY - Systems designed to adapt and evolve

   • Modularity, Economy, Generation, Extensibility

In practice: Code review checks “Does this embody Clarity?” not just “Is this correct?” Architecture decisions are evaluated against design rules. When design rules conflict (Simplicity vs. Robustness), the decision framework makes trade-offs explicit.

How They Enable Each Other

• Preamble enables Design Rules - Psychological safety makes it safe to discuss design principles and trade-offs without defensiveness
• Design Rules anchor Preamble - When teams have design principles to reference, disagreement becomes technical, not personal
• Together - Teams build systems that are both technically sound AND arrived at through trustworthy processes

Core Beliefs Behind the Playbook

1. Quality Shouldn’t Require Heroic Effort

Good processes make quality the default. The playbook instills review, testing, and security checks into every workflow-not as optional extras, but as built-in steps. This removes the question “should we review this?” (Answer: always.) It removes the question “should this be tested?” (Answer: always.)

When quality is the default, nobody has to argue for it.

2. Teams Learn Faster with Documented Patterns

Architectural decisions have reasons. Design patterns solve problems. These don’t need to be reinvented. The playbook provides a pattern library for async systems, database optimization, distributed systems, and core architecture-with real-world examples and trade-offs documented.

Don’t reinvent. Iterate on proven approaches.

3. Async-First Communication Scales Better

The playbook is designed for distributed teams. Instead of “let’s sync up,” it uses structured async patterns: decision records, standup templates, knowledge transfer checklists. Async-first doesn’t mean no synchronous communication; it means documenting decisions so people can participate across time zones.

4. Multi-Perspective Review Catches More Issues

A single code reviewer can miss things. The playbook uses five perspectives on every major piece of code:

• Code quality - Clarity, Modularity (design rules in practice)
• Security - Robustness, Transparency (design rules in practice)
• Product alignment - Simplicity, Clarity (design rules in practice)
• Testing - Robustness, Repair (design rules in practice)
• Performance - Optimization discipline (design rules in practice)

These perspectives catch different issues using design rules as shared language. A performance engineer might miss a security vulnerability. A security engineer might miss a test coverage gap. Together, they create a high bar for quality.

5. Structured Processes Enable Faster Iteration

Counterintuitive, but true: more process, faster delivery. Not because of the process itself, but because it reduces rework and prevents problems.

When you have a structured incident response process, you respond faster and make fewer mistakes. When you have documented architectural decisions grounded in design rules, design reviews move faster because context is already there. When you have a testing framework, developers write fewer bugs and spend less time in QA cycles.

The playbook provides the structure. You decide how strictly to enforce it based on change size.

How It Works: The Integrated System

The playbook isn’t 52 independent commands. It’s an integrated system grounded in two foundational frameworks that all others build on:

Foundational Frameworks

Two documents establish the complete philosophy:

• /pb-preamble - How teams think together (peer collaboration, psychological safety, correctness)
• /pb-design-rules - What teams build (17 classical design principles in 4 clusters)

Every command in the playbook assumes both frameworks. Every workflow integrates both.

Core Foundation Commands

Three commands translate the frameworks into SDLC structure:

• /pb-guide - The SDLC framework with 11 phases and quality gates (assumes preamble + design rules)
• /pb-standards - Working principles and collaboration norms (grounded in both frameworks)
• /pb-templates - Reusable commit, PR, and testing templates (guides both preamble and design rule thinking)

Planning Before Building

Before writing code:

• /pb-plan - Define scope, acceptance criteria, success metrics, risks
• /pb-adr - Document architectural decisions with rationale and trade-offs
• /pb-patterns - Reference architectural patterns for your specific problem
• /pb-observability - Plan monitoring before implementation
• /pb-performance - Identify performance requirements upfront

Iterative Development with Built-In Quality Gates

Code flows through the same review loop repeatedly:

• /pb-start - Create a feature branch with clear scope
• /pb-cycle - Self-review, then peer review, iterate
• /pb-testing - Unit, integration, end-to-end tests
• /pb-security - Security checklist
• /pb-standards - Code style and patterns
• /pb-commit - Atomic commits with meaningful messages
• /pb-pr - Pull request with context for reviewers

Multi-Perspective Review

Different reviewers bring different lenses:

• /pb-review-hygiene - Code quality and maintainability
• /pb-security - Security review
• /pb-review-tests - Test coverage
• /pb-logging - Logging standards
• /pb-review-product - Product alignment

Safe Release

Before production:

• /pb-release - Pre-release checklist
• /pb-release - Final gate by senior engineer
• /pb-deployment - Strategy choice (blue-green, canary, rolling)

Incident Response

When things break:

• /pb-incident - Assessment, severity, mitigation, recovery
• /pb-observability - Monitoring and alerting strategy
• Post-incident review with /pb-adr to document lessons learned

Team Operations

Scaling beyond one person:

• /pb-standup - Async daily standups for distributed teams
• /pb-knowledge-transfer - Structured knowledge transfer
• /pb-onboarding - Structured team member onboarding
• /pb-team - Retrospectives, feedback, growth

PREAMBLE: How teams think → DESIGN RULES: What they build
(Peer thinking, challenge assumptions) (Clarity, Simplicity, Robustness, Extensibility)
         ↓                                    ↓
    PLAN ← Scope + Architecture → DEVELOP ← Iterate + Test → REVIEW
     ↓ (with architecture decisions)  ↓ (with design rules)  ↓ (checking design rules)
     └─────────→ RELEASE ←──────────────────────┘
                   ↓
                OPERATE ← Monitor & Measure
                   ↓
            INCIDENT? ← Assess & Mitigate
                   ↓
               RECOVER ← Design for Robustness
                   ↓
        Document & Learn → Back to PLAN

Every step of the workflow is guided by both Preamble (peer thinking) and Design Rules (technical excellence).

Real-World Architecture: Where It Fits

The playbook sits at the intersection of code, people, and process:

graph TB
    subgraph "Code Level"
        A["Version Control<br/>(Git)"]
        B["Code Quality<br/>(Linters, Tests)"]
        C["Architecture<br/>(Patterns, Design)"]
    end

    subgraph "Process Level"
        D["Code Review<br/>(Multi-perspective)"]
        E["Release Management<br/>(Safe deployment)"]
        F["Incident Response<br/>(Systematic)"]
    end

    subgraph "People Level"
        G["Onboarding<br/>(Structured)"]
        H["Knowledge Transfer<br/>(Documented)"]
        I["Team Dynamics<br/>(Retrospectives)"]
    end

    A --> D
    B --> D
    C --> D
    D --> E
    E --> F
    F --> H
    H --> G
    G --> I

    style A fill:#e3f2fd
    style B fill:#e3f2fd
    style C fill:#e3f2fd
    style D fill:#fff3e0
    style E fill:#f3e5f5
    style F fill:#ffebee
    style G fill:#e1f5e1
    style H fill:#e1f5e1
    style I fill:#e1f5e1

When to Apply Full Process

For large, architectural changes (L-tier), you use all 11 sections:

1. Intake & clarification
2. Scope lock
3. Design & trade-offs
4. Implementation plan
5. Development (with testing, security, standards)
6. Testing & QA
7. Documentation
8. Pre-release review
9. Deployment
10. Monitoring & alerting
11. Post-deployment verification

When to Apply Lighter Process

For a simple bug fix (XS-tier), you use only the essential sections:

1. Brief intake (1 line in commit)
2. Fix the bug
3. Self-review
4. Atomic commit
5. Deploy and verify

The same playbook, right-sized to the change. No overhead for small changes. No skipped quality gates for any change.

Key Design Decisions

Decision 1: Why Change Tiers (XS / S / M / L)?

What we chose: Tier-based process that adjusts rigor based on change size.

Rationale:

• Typo fixes and bug fixes don’t need the same overhead as architectural changes
• But all changes need quality gates (testing, review, documentation)
• Tier-based approach lets teams be fast on small changes and thorough on large ones
• It also makes the process transparent: “This change is M-tier, so we need tech lead approval”

Alternative we rejected:

• Single fixed process for all changes - too heavy for small changes, creates burnout
• No process - fast initially, but quality degrades at scale

Decision 2: Why Multi-Perspective Review?

What we chose: Different reviewers (code, security, product, test, performance) instead of one person reviewing everything.

Rationale:

• A single reviewer is a bottleneck and also has blindspots
• A security engineer might miss test coverage gaps
• A performance engineer might miss design issues
• Different perspectives catch different issues
• For large changes, multiple reviewers provide redundancy: if one misses something, another catches it

Alternative we rejected:

• Single reviewer - faster but lower quality
• All reviewers always - slower, creates meetings bloat

Decision 3: Why Documented Architectural Decisions?

What we chose: /pb-adr command for recording decisions with rationale, trade-offs, and lessons learned.

Rationale:

• Architectural decisions are made once but affect the codebase for years
• Without documentation, future team members don’t understand “why” and make bad changes
• ADRs become institutional memory that survives team turnover
• Design reviews become faster when context is already documented

Alternative we rejected:

• Decisions in Slack - Lost when channel scrolls, no context for future developers
• Comments in code - Doesn’t scale, gets out of sync
• Wiki - Often abandoned, outdated, nobody knows where to look

Decision 4: Why Async-First for Distributed Teams?

What we chose: Structured async communication (standups, PRs, knowledge transfer) instead of sync meetings.

Rationale:

• Sync meetings don’t work well across 8+ time zones
• Async communication forces documentation, creating a record
• Async-first doesn’t mean no sync meetings; it means sync is intentional, not default
• People can think through complex topics instead of having to respond in real-time
• Time zones become irrelevant

Alternative we rejected:

• Sync meetings for everything - 8am one timezone is 6pm another
• Async communication with no structure - Decisions get lost, context disappears

Decision 5: Why Checkpoints Instead of Continuous Deployment?

What we chose: Structured gates (scope lock, design approval, release approval) instead of pushing every commit straight to production.

Rationale:

• Gates catch mistakes before they reach production
• They create opportunities for feedback on approach before implementation
• They provide a paper trail for audits and incident investigation
• They’re checkpoints, not blocks: a good design review takes 1 hour and prevents 2 weeks of rework

Alternative we rejected:

• No gates (continuous deployment) - Fast but mistakes reach production
• Heavy gates (multiple sign-offs) - Slower, creates bottlenecks

When to Use the Playbook

Excellent Fit

• New teams establishing culture and practices from day one
• Growing teams (5 → 50+ people) that need to scale processes
• Distributed teams working across time zones
• High-quality codebases where mistakes are expensive
• Teams using agentic development tools (Claude Code or others) optimizing workflows
• Organizations wanting to codify and transfer institutional knowledge

Not Ideal For

• Tiny teams (< 3 people) - Overhead outweighs benefits
• Prototypes that will be thrown away - Too much documentation
• Teams with deeply established workflows that work well - Migration cost too high
• Language-specific frameworks you’re deeply committed to (domain-specific commands exist but not complete)

Starting Points

• Greenfield project: Follow Scenario 1 (plan → architecture → develop → release)
• Existing codebase: Follow Scenario 2 (audit → establish baseline → integrate gradually)
• Individual developer: Use individual commands as needed; build as you grow
• Distributed team: Start with /pb-standup, /pb-knowledge-transfer, /pb-adr

Measuring Success

The playbook’s value shows up in:

Faster Code Review

• With documented architecture, reviewers don’t need to ask “why is it designed this way?”
• With clear standards, reviewers don’t need to nitpick style
• Multi-perspective review happens in parallel, not sequentially

Fewer Regressions

• Quality gates (testing, security, documentation) catch issues before production
• Atomic commits make it easy to identify which change broke something
• Documented decisions prevent breaking changes from architectural misunderstandings

Easier Onboarding

• New team members read /pb-guide and understand the SDLC
• ADRs explain “why” for every major decision
• Structured standup templates and knowledge transfer process accelerate knowledge sharing

Faster Incident Response

• /pb-incident provides a systematic assessment process
• Pre-documented rollback steps mean faster recovery
• Postmortem template ensures lessons are captured

Lower Burnout

• Structured processes mean less “how do we do this?” Slack threads
• Clear quality gates mean less endless revision cycles
• Async-first communication means less context-switching across time zones

Implementation Philosophy

The playbook isn’t a “fork and use” system. It’s a “fork, read, adapt, and use” system.

Each command includes:

• How it works - Concrete steps and examples
• Why we do it - Rationale and philosophy
• Where to customize - Instructions on adapting to your team

Your team’s context matters:

• Size - XS team vs. 100-person org
• Domain - Security-critical vs. user-facing frontend
• Maturity - Greenfield vs. 10-year-old codebase
• Culture - Startup vs. enterprise vs. open source

The playbook provides the framework. You adjust the rigor based on context.

What’s Included

Complete Framework + Command Library

Foundational Frameworks - /pb-preamble, /pb-design-rules (with expansions on specific contexts)

• Complete philosophy for peer collaboration and technical design
• Preamble expansion guides for async teams, power dynamics, decision discipline
• Design Rules organized into 4 clusters with decision framework

Core Foundation - /pb-guide, /pb-standards, /pb-documentation, /pb-templates

• SDLC framework with right-sized rigor
• Collaboration norms and quality standards
• Reusable templates for commits, PRs, decisions

Planning - /pb-plan, /pb-adr, /pb-patterns* (multiple families: async, core, database, distributed, security, cloud), /pb-performance, /pb-observability, /pb-deprecation

• Scope planning and architectural decisions
• Pattern library with trade-offs
• Design considerations before implementation

Development - /pb-start, /pb-cycle, /pb-resume, /pb-commit, /pb-pr, /pb-testing, /pb-standup, /pb-todo-implement, /pb-knowledge-transfer, /pb-what-next

• Feature branch establishment with clear scope
• Iteration cycles with self and peer review
• Atomic commits and pull requests
• Testing, async communication, knowledge transfer
• Contextual command recommendations

Deployment - /pb-deployment, /pb-incident

• Deployment strategies (blue-green, canary, rolling)
• Incident assessment, response, and recovery

Release - /pb-release

• Pre-release checklists and production sign-off

Review - /pb-review* (comprehensive, code, product, tests, docs, hygiene, microservice, prerelease), /pb-security, /pb-logging

• Multi-perspective code review with design rules as shared language
• Specialized audits (security, logging, architecture)

Repository - /pb-repo* (init, organize, readme, about, blog, enhance)

• Greenfield project initialization
• Repository structure and documentation

People - /pb-onboarding, /pb-team

• Structured team member onboarding
• Retrospectives and team dynamics
• Knowledge transfer processes

Reference - /pb-context

• Project working context and decision log template

Documentation

• Frameworks - Preamble and Design Rules with practical integration guides
• Command reference with real-world examples
• Integration guide showing framework and command relationships
• Decision guide for choosing the right command
• Getting started scenarios for different situations
• Quick references for daily lookup

Ready to Install

git clone https://github.com/vnykmshr/playbook.git
cd playbook
./scripts/install.sh  # Creates symlinks in ~/.claude/commands/

All commands are immediately available in Claude Code.

The Bigger Picture

Engineering teams face the same challenges repeatedly. The Playbook solves them with a complete philosophy that combines two complementary frameworks:

How It Works

1. The Preamble (HOW teams think) - Establishes peer collaboration, psychological safety, correctness over agreement
2. Design Rules (WHAT teams build) - Classical principles ensuring clarity, simplicity, robustness, extensibility
3. Together - Enable teams to build systems that are both technically excellent AND arrived at through trustworthy processes

What This Enables

1. Codifying proven practices - Don’t invent, iterate (grounded in design rules)
2. Documenting the “why” - Future decisions are informed by past decisions (enabled by preamble thinking)
3. Integrating systems - Commands work together as a coherent whole, not in isolation
4. Right-sizing rigor - Lightweight process for small changes, thorough for large ones
5. Scaling across time zones - Distributed teams stay aligned through structured async communication

The Result

Teams that ship faster, maintain higher quality, respond to incidents better, and experience less burnout.

Quality becomes the default. Not because of individual heroics, but because:

• Good processes are embedded in how work gets done (preamble thinking)
• Sound design is enforced at every step (design rules)
• Both frameworks work together to enable trust and excellence

Getting Started

Learn the Foundations First

The Preamble → Understand how teams think together: peer collaboration, challenge assumptions, correctness over agreement.

Design Rules → Understand what you build: 17 principles organized in 4 clusters (Clarity, Simplicity, Resilience, Extensibility).

Then Pick Your Scenario

Scenario 1: New Project → From greenfield to production with clear architecture and quality gates.

Scenario 2: Existing Codebase → Gradually adopt playbook practices without disrupting current flow.

Scenario 3: Daily Developer Workflow → See how a developer uses the playbook during a typical day.

Scenario 4: Code Review → Structure code review from multiple perspectives using design rules as shared language.

Scenario 5: Incident Response → Respond to production issues systematically, learning from failures.

Or Explore by Category

Browse the full command reference, decision guide, or quick references for daily use.

The Complete Philosophy

The playbook isn’t just documentation. It’s a decision framework that makes good development practices the default.

By integrating Preamble (peer thinking) with Design Rules (technical excellence), the playbook enables teams to:

• Think together without hierarchy - Challenge assumptions professionally, surface problems early
• Build systems that endure - Systems are clear, simple, and reliable by design
• Ship confidently - Quality gates catch mistakes before they reach production
• Scale without meetings - Distributed teams stay aligned through structured async communication
• Sustain momentum - Good processes prevent burnout, not increase it

The culmination of this work is a complete engineering philosophy-not separated into “soft skills” and “technical skills,” but integrated as a unified whole. Teams that adopt both the Preamble and Design Rules don’t just write better code. They build better teams.

Getting Started with the Engineering Playbook

Welcome to the Engineering Playbook! This guide will help you get up and running quickly.

Installation

See Installation & Setup in the main README for prerequisites and installation steps.

Quick summary:

git clone https://github.com/vnykmshr/playbook.git
cd playbook
./scripts/install.sh

With Claude Code: Commands available as skills (e.g., /pb-start) Without Claude Code: Read command files as Markdown (see Using Playbooks with Other Tools)

Quick Start: Five Scenarios

Pick the scenario that matches your situation:

Scenario 1: Starting a New Project

You’ve decided to build something new. Here’s how to establish a strong foundation:

# Step 1: Plan the project
/pb-plan              # Define scope, success criteria, phases

# Step 2: Set up repository
/pb-repo-init         # Initialize directory structure
/pb-repo-organize     # Clean folder layout
/pb-repo-readme       # Write compelling README

# Step 3: Document architecture
/pb-adr               # Record architectural decisions
/pb-patterns          # Reference relevant patterns

# Step 4: Begin development
/pb-start             # Create feature branch
/pb-cycle             # (Repeat) Self-review → Peer review → Commit
/pb-pr                # Create pull request

# Step 5: Release
/pb-release           # Pre-release checklist
/pb-deployment        # Choose deployment strategy

See: Integration Guide for complete workflow with step-by-step guidance

Scenario 2: Adopting Playbook in Existing Project

Your project already has code and processes. Let’s integrate the playbook gradually:

# Step 1: Understand current state
/pb-context           # Document project context and decisions
/pb-review-hygiene       # Audit existing code quality
/pb-review-hygiene    # Identify technical debt

# Step 2: Establish baseline
/pb-standards         # Define working principles for your team
/pb-guide             # Learn the SDLC framework
/pb-templates         # Create commit/PR templates

# Step 3: Begin structured development
/pb-start             # First feature with new workflow
/pb-cycle             # Use quality gates for code review
/pb-commit            # Structured commits

# Step 4: Scale practices
/pb-team              # Team retrospectives
/pb-knowledge-transfer # Document tribal knowledge
/pb-review-*          # Periodic reviews (monthly, quarterly)

# Step 5: Continuous improvement
/pb-incident          # Handle production issues systematically
/pb-adr               # Document major decisions
/pb-performance       # Optimize when needed

See: Integration Guide → “Scenario 2: Adopting Playbook”

Scenario 3: Typical Developer Day

You’re in the middle of a feature sprint. Here’s your daily rhythm:

# Morning: Get context
/pb-resume            # Recover context from yesterday
/pb-standup           # Write async standup for team

# Development: Code → Review → Commit (repeat)
/pb-cycle             # Self-review changes
  # Includes: /pb-testing, /pb-security, /pb-standards, /pb-documentation

/pb-commit            # Atomic, well-explained commit

# Before lunch: Big picture
/pb-context           # Refresh project context (decisions, roadmap)
/pb-patterns          # Reference patterns for next component

# Afternoon: Ready to merge?
/pb-cycle             # Final self-review
/pb-pr                # Create pull request with context

# End of day: Status
/pb-standup           # Update team on progress, blockers

See: Integration Guide → “Workflow 1: Feature Development”

Scenario 4: Code Review

A PR is ready for review. As a reviewer, you can follow a structured approach:

/pb-review-hygiene       # Code quality checklist
/pb-security          # Security perspective
/pb-review-tests      # Test coverage and quality
/pb-logging           # Logging standards verification
/pb-review-product    # Product alignment (if user-facing)

Each command provides a different lens on the same code, catching different categories of issues.

Scenario 5: Incident Response

Production is down. Execute quickly:

/pb-incident          # Assess severity, choose mitigation
  # Options: Rollback (fastest), Hotfix, Feature disable

/pb-observability     # Monitor recovery

# After incident (within 24h)
/pb-incident          # Comprehensive review
/pb-adr               # Document decision to prevent repeat

See: Integration Guide → “Workflow 3: Incident Response”

Next Steps

I’m not sure which scenario fits me…

Use the Decision Guide to find the right command for your situation.

I need more context…

Read the Integration Guide to understand how all commands work together.

I have a specific question…

Check the FAQ for common questions and answers.

I want to browse all commands…

See the Full Command Reference organized by category.

Key Principles to Remember

Quality at Every Step

Never skip the review step. Each iteration includes self-review, testing, security checks, and peer review before committing.

Atomic, Logical Commits

Create small commits that address one concern, are always deployable, and have clear messages explaining the “why.”

Multi-Perspective Reviews

Get feedback from different angles: code quality, security, product alignment, test coverage, and performance.

Documented Decisions

Record architectural decisions so future team members understand the reasoning, not just the code.

Processes, Not Rules

Adapt the playbook to your team’s needs. These are frameworks, not commandments.

Common Questions

Q: Do I have to follow the playbook exactly? A: No. The playbook provides frameworks and best practices. Adapt them to your team’s needs and context.

Q: Can I integrate the playbook gradually? A: Yes! See Scenario 2 (Adopting Playbook in Existing Project) for a gradual integration approach.

Q: Which scenario should I choose? A: Match your situation to the 5 scenarios above. If unsure, start with Scenario 3 (Typical Developer Day) to see how commands work together.

Q: What if I have other questions? A: Check the FAQ or open an issue on GitHub.

What to Read Next

1. Command Reference - Browse commands by category
2. Integration Guide - Understand how commands work together
3. Decision Guide - Find the right command for any situation
4. FAQ - Common questions and troubleshooting

Playbook Adoption Guide

Integrating the engineering playbook into your team’s workflow. This guide shows how to adopt across different team sizes and contexts.

Quick Start by Team Size

Startup (2-5 engineers)

• Week 1: Read /pb-guide (understand 11 phases) + /pb-preamble (collaboration style)
• Week 2: Start using /pb-start → /pb-cycle → /pb-commit → /pb-pr for feature work
• Week 3: Add /pb-review-hygiene for peer review, /pb-standards for decision-making
• Payoff: Clear development rhythm, better code review, shared decision language
• Effort: 2-3 hours per engineer for onboarding

Small Team (6-12 engineers)

• Phase 1 (Week 1-2):
  • Run workshop: /pb-guide (SDLC overview) + /pb-preamble (team collaboration)
  • Establish team norms from /pb-standards
  • Pick 3-4 core commands: /pb-start, /pb-cycle, /pb-commit, /pb-pr
• Phase 2 (Week 3-4):
  • Add /pb-plan for feature planning
  • Add /pb-review-hygiene + /pb-security for code review gates
  • Document team decisions in /pb-context
• Payoff: Structured planning, consistent code quality, documented decisions
• Effort: 4-6 hours per engineer over 4 weeks

Medium Team (13-30 engineers)

• Phase 1 (Week 1-2):
  • Lead architect reads entire playbook
  • Creates team guide: custom command selection + team-specific examples
  • Runs workshops for different roles (frontend, backend, infra, QA)
• Phase 2 (Week 3-4):
  • Rollout core workflow: /pb-plan → /pb-adr → /pb-cycle → /pb-review-* → /pb-release
  • Establish review ceremony using /pb-review-hygiene, /pb-review-tests
  • Create project /pb-context document for current work
• Phase 3 (Week 5-8):
  • Integrate /pb-patterns-* into architecture discussions
  • Establish release process using /pb-release + /pb-deployment
  • Monitor adoption via /pb-review (periodic) and /pb-standards (decisions)
• Payoff: Scaled decision-making, architecture consistency, knowledge sharing
• Effort: 6-8 hours initial per engineer, 1-2 hours/week ongoing

Large Team (30+ engineers) or Multiple Teams

• Phase 1:
  • Platform/core team leads customize playbook
  • Create role-specific subsets (frontend guide, backend guide, SRE guide)
  • Run quarterly strategy sessions using /pb-preamble and /pb-design-rules
• Phase 2:
  • Rollout 8-week adoption program with checkpoints
  • Pair experienced + new engineers on /pb-cycle and /pb-todo-implement
  • Establish command adoption metrics (% using core workflow)
• Payoff: Org-wide consistency, reduced onboarding time, better incident response
• Effort: Ongoing, integrate into new engineer onboarding

4-Phase Adoption Pathway

Phase 1: Foundation (Weeks 1-2)

Goal: Team understands philosophy and core workflow

Activities:

• Team reads /pb-guide (1-2 hours) and /pb-preamble (30 min)
• Lead architect reads /pb-design-rules and creates team-specific reference
• Establish working group: core decision-makers + IC representatives
• Define team’s tier system (XS/S/M/L) for task sizing

Success Signals:

• 80%+ team members attended workshop
• Shared understanding of 11 SDLC phases
• Written team norms (from /pb-standards)

Phase 2: Development Workflow (Weeks 3-4)

Goal: Daily development process uses playbook

Activities:

• Integrate /pb-start → /pb-cycle → /pb-commit → /pb-pr into real features
• Use /pb-testing alongside /pb-cycle for test-driven development
• Establish review process: /pb-review-hygiene for every PR
• Create project /pb-context document for current decisions
• Track metrics: % of features using playbook workflow

Success Signals:

• 50%+ of PRs reference playbook commands in PR description
• Code review feedback uses /pb-review-hygiene language
• Commit messages follow /pb-templates format

Phase 3: Planning & Architecture (Weeks 5-8)

Goal: Major decisions documented using playbook frameworks

Activities:

• Next feature uses /pb-plan + /pb-adr workflow
• Architecture decisions reference applicable /pb-design-rules
• Team uses /pb-patterns-* for system design
• Add /pb-observability and /pb-performance to planning
• Establish /pb-review (monthly) and /pb-review-tests (monthly) cadence

Success Signals:

• All major features have /pb-adr documents
• Design discussions explicitly reference design rules
• Monthly review ceremonies happening

Phase 4: Release & Operations (Weeks 9+)

Goal: Production safety and incident response follow playbook

Activities:

• Implement /pb-release checklist before every release
• Use /pb-deployment for deployment strategy selection
• Establish incident response using /pb-incident
• Connect observability to /pb-observability strategy
• Run quarterly /pb-team retrospectives

Success Signals:

• 100% of releases use /pb-release checklist
• Incident response time reduced
• Team retention improved (per /pb-team feedback)

Adoption by Context

By Codebase Maturity

By Team Distribution

By Risk Profile

Measuring Success

Adoption Metrics (Track weekly)

• % of engineers actively using core commands
• % of features following /pb-start → /pb-cycle → /pb-pr workflow
• % of PRs using /pb-review-hygiene perspective
• % of major decisions documented in /pb-adr

Quality Metrics (Track monthly)

• Code review feedback quality (using design rules language)
• Test coverage maintenance
• Security issue density (post /pb-security adoption)
• Deployment success rate (post /pb-release + /pb-deployment adoption)

Team Metrics (Track quarterly)

• Time to onboard new engineer (-30% after 3 months)
• Team satisfaction with decision-making (+20% per /pb-team surveys)
• Incident response time (-25% average)
• Knowledge retention across team transitions

Common Pitfalls & Solutions

Implementation Checklist

Before Launch

• Leadership team reads /pb-guide and /pb-preamble
• Select initial command set (recommend: 5-7 commands to start)
• Customize examples for your tech stack
• Identify 2-3 “playbook champions” to drive adoption
• Schedule workshops

Week 1-2: Kickoff

• Run 60-min workshop: /pb-guide overview + /pb-preamble
• Create team guide document
• Establish /pb-context for current project
• Share adoption timeline

Week 3-8: Rollout

• Weekly 30-min “command spotlight” sessions
• Include playbook reference in PR templates
• Track adoption metrics
• Address questions/concerns in Slack #playbook channel

Month 3+: Iterate

• Run /pb-team retrospective on adoption
• Refine command set based on feedback
• Expand to advanced commands
• Document team-specific customizations

FAQ

Q: Do we need to use ALL commands? A: No. Start with 5-7 core commands; expand based on team needs.

Q: How long does adoption take? A: 4-8 weeks to establish core workflow; 12 weeks to full integration.

Q: What if we’re already using different processes? A: Use playbook commands that fill gaps or improve existing process. Merge gradually.

Q: Should we customize the playbook? A: Yes. Keep philosophy intact; customize examples, tools, and process for your team.

Q: How do we handle team pushback? A: Connect to pain points: “ADRs solve our knowledge loss problem” or “Design rules help us debate architecture better.”

Start with Phase 1 this week. Pick 4 core commands. Add one workshop. Measure adoption in 30 days.

Workflows: How Commands Work Together

The Engineering Playbook is organized around major workflows. This page shows how commands combine to solve real problems.

Feature Development Workflow

From planning through production, here’s how commands work together to deliver features:

PLANNING PHASE        DEVELOPMENT PHASE       CODE REVIEW PHASE     RELEASE PHASE
│                     │                       │                      │
├─ /pb-plan           ├─ /pb-start            ├─ /pb-cycle           ├─ /pb-release
│                     │                       │                      │
├─ /pb-adr            ├─ /pb-cycle (iterate)  ├─ /pb-testing         ├─ /pb-deployment
│                     │                       │                      │
├─ /pb-patterns-*     ├─ /pb-testing          ├─ /pb-security        └─ Verify in
│                     │                       │                         production
├─ /pb-observability  ├─ /pb-security         ├─ /pb-logging
│                     │                       │
└─ /pb-performance    ├─ /pb-standards        ├─ /pb-review-*
                      │
                      ├─ /pb-documentation
                      │
                      ├─ /pb-commit
                      │
                      └─ /pb-pr

Step-by-Step Execution

1. Plan Phase (before coding)

   • /pb-plan - Lock scope, define success criteria, identify risks
   • /pb-adr - Document architectural decisions
   • /pb-patterns-* - Reference relevant patterns (core, async, database, distributed)
   • /pb-observability - Plan monitoring and observability requirements
   • /pb-performance - Identify performance targets and constraints

2. Development Phase (iterative)

   • /pb-start - Create feature branch, establish iteration rhythm
   • /pb-cycle - Develop feature:
     • Write code following /pb-standards
     • Include tests as you code (/pb-testing)
     • Review logging strategy (/pb-logging)
     • Update documentation (/pb-documentation)
     • Self-review changes
     • Request peer review (quality gates)
   • Repeat until feature is complete

3. Code Review Phase (before merging)

   • /pb-cycle - Iterate on feedback if needed
   • /pb-testing - Verify test coverage and quality
   • /pb-security - Security checklist during review
   • /pb-logging - Logging standards validation
   • /pb-review-* - Additional specialized reviews as needed:
     • /pb-review-hygiene - Code quality and patterns
     • /pb-review-product - Product alignment (if user-facing)
     • /pb-review-tests - Test suite depth and coverage
     • /pb-release - Final senior engineer review

4. Commit & PR Phase

   • /pb-commit - Create atomic, well-formatted commit(s)
   • /pb-pr - Create pull request with context and rationale

5. Release Phase (after merge)

   • /pb-release - Pre-release checklist (security, performance, docs)
   • /pb-deployment - Choose deployment strategy (blue-green, canary, rolling)
   • Verify in production (monitor, observe)

Incident Response Workflow

When production is down, this workflow guides rapid assessment and recovery:

INCIDENT DECLARED     ASSESSMENT               MITIGATION            RECOVERY           POST-INCIDENT
│                     │                        │                      │                  │
├─ PAGE ONCALL        ├─ /pb-incident          ├─ Rollback (fastest)  ├─ /pb-observability├─ /pb-incident
│                     │   (Severity: P0-P3)    │                      │                  │   (Root cause
├─ GATHER INFO        │                        ├─ Hotfix (targeted)   ├─ MONITOR          │    analysis)
│                     ├─ Identify root         │                      │                  │
└─ ESTABLISH          │   cause (quick)        └─ Feature disable     └─ Verify health  └─ /pb-adr
  COMMAND POST        │                           (safest)                                (Document
                      └─ Choose strategy                                                 decision)

Step-by-Step Execution

1. Incident Declaration (0 minutes)

   • Page oncall engineer or incident lead
   • Establish command post (Slack channel, bridge, etc.)
   • Gather initial information (what’s broken, who’s affected, customer impact)

2. Assessment Phase (0-5 minutes)

   • /pb-incident - Run triage checklist:
     • What’s the severity? (P0 = all users, P1 = major subset, P2 = feature, P3 = minor)
     • Quick root cause hypothesis?
     • What’s the fastest mitigation? (rollback, hotfix, disable feature)
   • Decide: Rollback, Hotfix, or Feature Disable?

3. Mitigation Phase (5-30 minutes, depending on strategy)

   • Rollback (fastest, 5-10 min) - Revert last deployment
   • Hotfix (targeted, 15-30 min) - Emergency fix, test, deploy
   • Feature Disable (safest, 5-15 min) - Kill feature flag, keep code

4. Recovery & Monitoring (30+ minutes)

   • /pb-observability - Monitor key metrics during recovery:
     • Error rates returning to baseline?
     • Latency normalized?
     • User-visible impact resolved?
   • Maintain open communication with stakeholders

5. Post-Incident (within 24 hours)

   • /pb-incident - Comprehensive incident review:
     • What was the root cause?
     • How did we miss it pre-deployment?
     • What’s the permanent fix?
   • /pb-adr - Document decision to prevent recurrence
   • Schedule permanent fix into sprint

Team Onboarding Workflow

Bringing new team members up to speed systematically:

PREPARATION           FIRST DAY               FIRST WEEK             RAMP-UP             GROWTH & GROWTH
│                     │                       │                      │                  │
├─ /pb-onboarding     ├─ /pb-start            ├─ /pb-knowledge-      ├─ /pb-cycle        ├─ /pb-team
│   (Setup access)    │   (orientation)       │   transfer           │   (first feature)  │   (feedback)
│                     │                       │                      │                  │
├─ SETUP DEV ENV      ├─ INTRO TO CODEBASE    ├─ /pb-guide           ├─ /pb-pr           ├─ RETROSPECTIVE
│                     │                       │   (SDLC framework)   │                  │
├─ ASSIGN MENTOR      ├─ ROLE CLARIFICATION   ├─ /pb-standards       └─ Peer review     └─ CAREER
│                     │                       │   (working principles)    feedback        DEVELOPMENT
└─ DOCS ACCESS        └─ CALENDAR INVITES     └─ /pb-context
                                              (decisions, roadmap)

Step-by-Step Execution

1. Preparation Phase (before hire starts)

   • /pb-onboarding - Prepare:
     • Set up development environment
     • Create accounts and access
     • Assign mentor/buddy
     • Gather documentation

2. First Day

   • /pb-start - Orientation:
     • Welcome, team introductions
     • Development environment walkthrough
     • Assign initial tasks
   • Set up calendar invites for regular syncs

3. First Week

   • /pb-knowledge-transfer - Transfer knowledge:
     • System architecture overview
     • Key decision history
     • Code organization tour
   • /pb-guide - Learn SDLC framework:
     • 11 phases of development
     • Quality gates
     • Review process
   • /pb-standards - Learn working principles:
     • Coding standards
     • Communication norms
     • Collaboration expectations
   • /pb-context - Understand project:
     • Current roadmap
     • Major decisions
     • Team priorities

4. Ramp-Up Phase (weeks 2-4)

   • /pb-cycle - Contribute first feature:
     • Pick small feature or bug fix
     • Follow full cycle (plan → develop → review → commit → PR)
     • Get peer feedback
   • Request review, fix feedback, merge PR
   • Build confidence in workflow

5. Growth Phase (ongoing)

   • /pb-team - Team feedback:
     • Retrospectives
     • 1-on-1s
     • Career development
   • Increase ownership and autonomy
   • Mentor future team members

Periodic Quality Reviews Workflow

Regular check-ins on different aspects of code and team health:

MONTHLY CADENCE       QUARTERLY CADENCE       AS-NEEDED
│                     │                       │
├─ /pb-review-hygiene    ├─ /pb-review-hygiene  ├─ /pb-review (comprehensive)
│   (Quality)         │   (Tech debt)        │
│                     │                       ├─ /pb-performance
├─ /pb-review-tests   ├─ /pb-review-product  │   (Bottlenecks)
│   (Coverage)        │   (Fit & vision)     │
│                     │                       ├─ /pb-review-docs
└─ /pb-logging        └─ Team retrospective   │   (Accuracy)
   (Standards)                               └─ /pb-release
                                                (Before release)

Recommended Schedule

Pattern Selection Workflow

When designing a new feature or system, follow this workflow to select and combine patterns:

UNDERSTAND PROBLEM    SELECT CORE PATTERN     IDENTIFY ASYNC NEEDS  COMPLETE DESIGN
│                     │                       │                      │
├─ Define constraints ├─ /pb-patterns-core    ├─ /pb-patterns-async  ├─ /pb-adr
│                     │   (SOA, events, etc.) │   (callbacks,         │   (Record decision)
├─ Identify goals     │                       │    promises, etc.)   │
│                     ├─ Check for conflicts/ ├─ /pb-patterns-db     ├─ /pb-observability
├─ Consider scale     │   composition         │   (pooling, etc.)     │   (Monitoring plan)
│                     │                       │                      │
└─ Review constraints └─ Validate trade-offs  ├─ /pb-patterns-       └─ /pb-performance
                                             │   distributed         (Perf targets)
                                             │   (saga, CQRS, etc.)
                                             │
                                             └─ Plan combinations

Step-by-Step Execution

1. Understand Problem

   • Define requirements and constraints
   • Identify scalability goals
   • List non-functional requirements (latency, throughput, consistency)

2. Select Architectural Pattern (/pb-patterns-core + /pb-patterns-resilience)

   • Architecture: SOA, Event-Driven, Strangler Fig (core)
   • Resilience: Retry, Circuit Breaker, Rate Limiting (resilience)
   • Match pattern to problem
   • Check for conflicts with existing architecture

3. Identify Async Needs (/pb-patterns-async)

   • Do you need callbacks, promises, async/await, reactive streams?
   • Worker threads or job queues?
   • Real-time vs. eventual consistency?

4. Database Considerations (/pb-patterns-db)

   • Connection pooling strategy?
   • Query optimization needed?
   • Replication or sharding?

5. Distributed System Patterns (/pb-patterns-distributed)

   • Multiple services / microservices?
   • Need saga or distributed transactions?
   • CQRS for read/write separation?

6. Document Decision (/pb-adr)

   • Record pattern choices
   • Explain trade-offs
   • Document alternative considered

7. Plan Observability (/pb-observability)

   • How will you monitor?
   • Key metrics to track?
   • Alerting strategy?

8. Set Performance Targets (/pb-performance)

   • Latency requirements?
   • Throughput targets?
   • Resource limits?

Daily Workflow

A typical day for an engineer using the playbook:

MORNING               MIDDAY                AFTERNOON               END OF DAY
│                     │                      │                      │
├─ /pb-resume         ├─ /pb-context         ├─ /pb-cycle            ├─ /pb-pause
│ (Get context)       │ (Big picture)        │ (Final self-review)   │ (Preserve context)
│                     │                      │                      │
├─ /pb-standup        ├─ /pb-patterns        ├─ Ready to ship?       └─ Update trackers,
│ (Write standup)     │ (Plan next work)     │  → /pb-ship             document state
│                     │                      │
└─ /pb-cycle          └─ /pb-cycle           └─ Code review feedback
  (Self-review)         (Develop feature)        (Address if needed)
  (Peer review if ready)

Session boundaries: /pb-pause and /pb-resume work as bookends-pause preserves context at end of session, resume recovers it at start of next.

Shipping: When focus area is code-complete, use /pb-ship for the full journey: specialized reviews → PR → peer review → merge → release → verify.

Next Steps

• Decision Guide - Find the right command for any situation
• Command Reference - Browse all commands
• Integration Guide - Deep dive on command relationships

Workflow Recipes

Pre-built command sequences for common development scenarios. Each recipe links commands into a coherent workflow, showing exactly when to use which command.

Philosophy: Commands are precision tools. Recipes show how to combine them effectively. Think of recipes as “playbooks within the playbook.”

Quick Reference

Discovery tip: All recipes use the recipe- prefix for easy search and tab completion.

recipe-bug-fix

Scenario: Fixing bugs, from simple typos to complex investigations Tier: S (simple) or M (complex)

Workflow

1. /pb-start
   └─ Create fix/issue-123 branch

2. /pb-debug (if cause unclear)
   └─ Reproduce → Isolate → Hypothesize → Test

3. /pb-cycle
   └─ Fix → Self-review → Test
   └─ Repeat until fix is solid

4. /pb-commit
   └─ fix(scope): description
   └─ Fixes #123

5. /pb-pr
   └─ Summary: What was broken, how it's fixed
   └─ Test plan: How to verify

→ Merge after approval

Checklist

• Bug reproduced before fixing
• Root cause addressed (not just symptom)
• Regression test added
• No unrelated changes included

recipe-feature

Scenario: Building new features end-to-end Tier: M or L

Workflow

1. /pb-plan
   └─ Discovery: What problem? What boundaries?
   └─ Scope lock: In/out of scope, success criteria

2. /pb-adr (if architectural decisions needed)
   └─ Document alternatives, trade-offs, decision

3. /pb-start
   └─ Create feature/feature-name branch

4. /pb-cycle (repeat)
   └─ Implement → Self-review → Test
   └─ /pb-commit for each logical chunk

5. /pb-ship
   └─ Phase 1: Quality gates
   └─ Phase 2: Specialized reviews
   └─ Phase 3: Final gate
   └─ Phase 4: PR & peer review
   └─ Phase 5: Merge & release

6. /pb-release (if production deployment)
   └─ Deploy → Verify → Monitor

Checklist

• Scope locked before implementation
• Changes are atomic (one concern per commit)
• Tests cover happy path and key edge cases
• Documentation updated
• No scope creep

recipe-frontend

Scenario: Frontend/UI feature development with design language and accessibility Tier: M or L

Workflow

1. /pb-plan
   └─ What problem? Who benefits?
   └─ Scope lock

2. /pb-design-language (if new project or new patterns)
   └─ Define tokens, vocabulary, constraints
   └─ Request/create required assets

3. /pb-patterns-frontend
   └─ Choose component patterns
   └─ Plan state management approach
   └─ Consider performance implications

4. /pb-start
   └─ Create feature/feature-name branch

5. /pb-cycle (repeat)
   └─ Build components (mobile-first)
   └─ /pb-a11y checks during development
   └─ Self-review → Test → Commit

6. /pb-ship
   └─ Include /pb-a11y checklist in reviews
   └─ Performance audit (bundle size, load time)

7. /pb-release
   └─ Deploy → Cross-browser testing → Monitor

Frontend-Specific Checklist

• Mobile-first implemented (styles build up, not down)
• Theme-aware (uses design tokens, supports dark mode)
• Semantic HTML used (not div soup)
• Keyboard navigable (Tab, Enter, Escape)
• Screen reader tested
• Assets optimized (images, fonts)
• Bundle size acceptable

recipe-api

Scenario: API design and implementation Tier: M

Workflow

1. /pb-plan
   └─ Who consumes this API?
   └─ What operations needed?

2. /pb-patterns-api
   └─ Choose style (REST, GraphQL, gRPC)
   └─ Design resources/schema
   └─ Define error handling

3. /pb-adr (if significant decisions)
   └─ Document API style choice, versioning strategy

4. /pb-start
   └─ Create feature/api-name branch

5. /pb-cycle (repeat)
   └─ Implement endpoint
   └─ Write API tests
   └─ Update documentation (OpenAPI)
   └─ Commit

6. /pb-security
   └─ Authentication/authorization review
   └─ Input validation
   └─ Rate limiting

7. /pb-ship → /pb-release

API-Specific Checklist

• OpenAPI/GraphQL schema documented
• Error responses consistent
• Authentication implemented
• Rate limiting configured
• Backward compatible (or version bumped)

recipe-incident

Scenario: Production incident response and recovery Tier: Emergency

Workflow

1. /pb-incident
   └─ ASSESS: What's broken? Who's affected?
   └─ MITIGATE: Rollback, disable, scale (stop bleeding)
   └─ COMMUNICATE: Status to stakeholders

2. /pb-debug (after bleeding stopped)
   └─ Reproduce → Isolate → Hypothesize
   └─ Find root cause

3. /pb-start (expedited)
   └─ Create hotfix/incident-123 branch

4. /pb-cycle (minimal)
   └─ Fix → Quick self-review → Test critical path

5. /pb-commit
   └─ fix(scope): hotfix for incident-123

6. /pb-pr (expedited review)
   └─ Sync review, not async

7. Deploy immediately
   └─ Verify fix in production
   └─ Monitor closely

8. Post-incident (within 24-48 hours)
   └─ Document timeline
   └─ Root cause analysis
   └─ Action items to prevent recurrence

Incident Checklist

• Mitigation applied (bleeding stopped)
• Stakeholders notified
• Fix verified in production
• Post-incident review scheduled

recipe-context-switch

Scenario: Pausing and resuming work across sessions Tier: N/A (operational)

Pausing Work

1. /pb-pause
   └─ Commit or stash current work
   └─ Push to remote
   └─ Update tracker (if applicable)
   └─ Write pause notes (todos/pause-notes.md)

Resuming Work

1. /pb-resume
   └─ git status, git log (current state)
   └─ Read pause notes
   └─ Sync with main (git fetch, rebase)
   └─ Verify environment (make dev, make test)

2. /pb-what-next (if unsure)
   └─ Context-aware recommendations

Context Switch Checklist

Before switching:

• Work committed or stashed
• Pushed to remote
• Pause notes written

When returning:

• Pause notes read
• Branch up to date
• Tests passing

recipe-onboarding

Scenario: New team member integration Tier: N/A (operational)

New Team Member Workflow

Week 1:
1. /pb-preamble
   └─ Understand collaboration philosophy
   └─ Challenge assumptions, peer thinking

2. /pb-design-rules
   └─ Understand technical principles
   └─ Clarity, Simplicity, Resilience, Extensibility

3. /pb-guide
   └─ Understand SDLC framework
   └─ Change tiers, checkpoints

4. /pb-standards
   └─ Code quality expectations
   └─ Commit and PR standards

Week 2:
5. /pb-onboarding (formal)
   └─ Codebase walkthrough
   └─ Architecture overview
   └─ Key contacts

6. First task (XS or S tier)
   └─ /pb-start → /pb-cycle → /pb-commit → /pb-pr
   └─ Experience the workflow

Week 3+:
7. /pb-knowledge-transfer
   └─ Deep dive into specific areas
   └─ Pair with senior engineer

Onboarding Checklist

• Preamble philosophy understood
• Development environment working
• Access to all required systems
• First PR merged
• Key architecture understood

recipe-release

Scenario: Pre-release preparation and deployment Tier: L

Pre-Release Workflow

1. /pb-review (comprehensive)
   └─ Security audit
   └─ Performance review
   └─ Test coverage analysis
   └─ Code quality review

2. /pb-release (final gate)
   └─ Senior engineer sign-off
   └─ Go/no-go decision

3. /pb-release
   └─ Version bump
   └─ Changelog update
   └─ Tag release
   └─ Deploy to production
   └─ Smoke test
   └─ Monitor for 1-24 hours

4. Post-release
   └─ Announce release
   └─ Monitor metrics
   └─ Be ready for hotfix if needed

Release Checklist

• All planned features complete
• All tests passing
• Security review complete
• Documentation updated
• Changelog updated
• Rollback plan ready
• Team available for monitoring

Recipe Selection Guide

What are you doing?

├─ Fixing a bug
│   └─ Simple bug? → Bug Fix recipe
│   └─ Complex investigation? → Add /pb-debug first
│
├─ Building something new
│   └─ Backend/API? → API Development recipe
│   └─ Frontend/UI? → Frontend Feature recipe
│   └─ Full stack? → Feature Development recipe
│
├─ Handling emergency
│   └─ Production down? → Incident Response recipe
│
├─ Switching context
│   └─ Leaving? → /pb-pause
│   └─ Returning? → /pb-resume
│
├─ Preparing release
│   └─ Release Preparation recipe
│
└─ Joining team
    └─ Onboarding recipe

Creating Custom Recipes

For project-specific workflows, create recipes in todos/recipes/ or docs/team-recipes.md:

## Recipe: [Name]

**When to use:** [Scenario]
**Tier:** [XS/S/M/L]

### Workflow

1. Command 1
   └─ What to do

2. Command 2
   └─ What to do

### Checklist

- [ ] Item 1
- [ ] Item 2

Related Commands

• /pb-what-next - Intelligent command recommendations
• /pb-guide - Full SDLC framework
• /pb-ship - Complete shipping workflow

Frontend Development Workflow

Complete guide to frontend development using the Engineering Playbook. Covers the full lifecycle from design to deployment.

Philosophy: Mobile-first, theme-aware, accessible by default. Build the simple version first, then enhance.

Quick Start

New frontend project?

/pb-repo-init → /pb-design-language → /pb-patterns-frontend → /pb-start

Adding frontend feature?

/pb-start → /pb-patterns-frontend → /pb-a11y → /pb-cycle → /pb-ship

Frontend code review?

/pb-cycle (self-review) → /pb-a11y checklist → /pb-review-hygiene

The Frontend Command Stack

Phase 1: Foundation - Design Language

Before writing component code, establish the design language.

New Projects

/pb-design-language

This command guides you through creating:

• Design tokens (colors, typography, spacing, motion)
• Component vocabulary (naming conventions)
• Constraints (what you don’t do)
• Asset requirements (logos, icons, images)

Output: docs/design-language.md - living document that evolves with the project.

Existing Projects

If joining an existing project:

1. Read existing docs/design-language.md (or equivalent)
2. Understand the token system
3. Follow established vocabulary

Key Decisions at This Phase

Phase 2: Architecture - Component Patterns

Plan component structure before implementation.

/pb-patterns-frontend

Key Decisions

Component Organization:

components/
├── atoms/          # Button, Input, Icon
├── molecules/      # SearchField, UserAvatar
├── organisms/      # Header, ProductCard
├── templates/      # PageLayout, DashboardLayout
└── pages/          # Actual route pages

State Management:

State type?
├─ Single component → useState
├─ Parent-child sharing → Lift state up
├─ Deep nesting → Context
├─ Server data → React Query / SWR
├─ Complex client state → Zustand / Redux
└─ URL state → useSearchParams

Mobile-First Checklist:

• Base styles are for mobile (smallest viewport)
• min-width media queries (not max-width)
• Touch targets 44x44px minimum
• Layouts work at 320px width

Phase 3: Accessibility - Built In, Not Bolted On

Accessibility is part of development, not a separate phase.

/pb-a11y

During Component Development

For EVERY component, verify:

• Semantic HTML - Using correct elements (<button>, <nav>, <main>)
• Keyboard accessible - Tab, Enter, Escape work
• Focus visible - Focus ring shows in all themes
• Labels present - All inputs have labels (visible or aria-label)
• Alt text - All informative images have alt text

Quick Semantic HTML Reference

Testing Accessibility

Manual (every feature):

1. Tab through - logical order?
2. Enter/Space - activates buttons?
3. Escape - closes modals?
4. Screen reader - announces correctly?

Automated (in CI):

# axe-core in tests
npm install @axe-core/playwright

Phase 4: API Integration

When frontend needs backend data.

/pb-patterns-api

Data Fetching Pattern

// Server state with React Query
const { data, isLoading, error } = useQuery({
  queryKey: ['user', userId],
  queryFn: () => fetchUser(userId),
});

// Optimistic updates for mutations
const mutation = useMutation({
  mutationFn: updateUser,
  onMutate: async (newData) => {
    // Cancel outgoing refetches
    await queryClient.cancelQueries(['user', userId]);
    // Snapshot previous value
    const previous = queryClient.getQueryData(['user', userId]);
    // Optimistically update
    queryClient.setQueryData(['user', userId], newData);
    return { previous };
  },
  onError: (err, newData, context) => {
    // Rollback on error
    queryClient.setQueryData(['user', userId], context.previous);
  },
});

Error Handling Pattern

// Consistent error boundary
<ErrorBoundary fallback={<ErrorFallback />}>
  <Suspense fallback={<Loading />}>
    <UserProfile />
  </Suspense>
</ErrorBoundary>

Phase 5: Development Iteration

The core development loop.

/pb-cycle

Frontend Self-Review Checklist

Before requesting peer review:

Functionality:

• Feature works on mobile viewport
• Feature works on desktop viewport
• Feature works in light mode
• Feature works in dark mode
• Loading states handled
• Error states handled
• Empty states handled

Accessibility:

• Keyboard navigation works
• Screen reader announces correctly
• Focus management correct (modals, drawers)
• Color contrast sufficient

Performance:

• No unnecessary re-renders (React DevTools)
• Images optimized
• Bundle size reasonable

Code Quality:

• Component is focused (single responsibility)
• Props are minimal and clear
• No hardcoded colors (use tokens)
• No hardcoded breakpoints (use tokens)

Commit Pattern

# Component commits
feat(Button): add loading state variant
feat(Header): implement responsive navigation

# Style commits
style(tokens): add dark mode color variants
style(Button): adjust hover state for accessibility

# Accessibility commits
a11y(Modal): add focus trap and escape handling
a11y(Form): add aria-describedby for error messages

Phase 6: Quality - Ship Workflow

When feature is code-complete.

/pb-ship

Frontend-Specific Review Focus

Phase 2 reviews for frontend:

Performance audit (add to Phase 2):

# Bundle analysis
npm run build -- --analyze

# Lighthouse audit
npx lighthouse http://localhost:3000 --view

Pre-Merge Checklist

• All self-review items verified
• Accessibility audit passed
• Cross-browser tested (Chrome, Firefox, Safari)
• Mobile tested (real device or emulator)
• Performance acceptable (bundle size, load time)
• No console errors or warnings

Common Frontend Recipes

Recipe: New Component

1. /pb-design-language
   └─ Check: Does vocabulary exist for this component?
   └─ If not: Define name, variants, states

2. /pb-patterns-frontend
   └─ Choose pattern: Atomic level, composition approach

3. Build component
   └─ Start mobile-first
   └─ Use design tokens
   └─ Add keyboard support

4. /pb-a11y checklist
   └─ Semantic HTML
   └─ ARIA if needed
   └─ Focus management

5. /pb-cycle
   └─ Self-review → Test → Commit

Recipe: Design System Update

1. /pb-design-language
   └─ Update tokens or vocabulary
   └─ Document in decision log

2. /pb-adr (if significant)
   └─ Document alternatives, trade-offs

3. Update components
   └─ One component per commit

4. /pb-ship
   └─ Visual regression check

Recipe: Accessibility Remediation

1. /pb-a11y
   └─ Audit existing component
   └─ Create issue list

2. /pb-start
   └─ Create a11y/component-name branch

3. Fix issues
   └─ One issue per commit
   └─ Test with screen reader

4. /pb-cycle → /pb-ship

Tools Quick Reference

Related Commands

• /pb-design-language - Design token and vocabulary system
• /pb-patterns-frontend - Component and state patterns
• /pb-a11y - Accessibility deep-dive
• /pb-patterns-api - API integration patterns
• /pb-debug - Frontend debugging techniques
• /pb-testing - Component testing patterns

Quick Decision Tree

What are you doing?

├─ Starting new frontend project
│   └─ /pb-design-language → /pb-patterns-frontend → /pb-start
│
├─ Building a component
│   └─ Check /pb-design-language → Build → /pb-a11y check → /pb-cycle
│
├─ Connecting to API
│   └─ /pb-patterns-api → /pb-patterns-frontend (state section)
│
├─ Reviewing frontend code
│   └─ /pb-a11y checklist → /pb-review-hygiene
│
├─ Fixing accessibility issue
│   └─ /pb-a11y → Fix → Test with screen reader
│
└─ Shipping frontend feature
    └─ /pb-ship (include /pb-a11y in Phase 2)

Version: 1.0

Decision Guide: Which Command Should I Use?

This guide helps you find the right command for any situation. Answer the questions to get directed to the command you need.

Quick Command Finder

I’m starting new work…

Starting a new project? → Use /pb-plan to lock scope, then /pb-repo-init to set up structure

Starting a feature or bug fix? → Use /pb-start to create a branch and establish iteration rhythm

Resuming after a break? → Use /pb-resume to get back in context

Looking at code that needs review? → Go to Code Review Questions

I’m in the middle of development…

Need to understand current patterns and architecture? → Use /pb-context to document and reference project context

Want to reference design patterns for what you’re building? → Use /pb-patterns for overview, then:

• /pb-patterns-core for architectural patterns (SOA, events, repository, DTO)
• /pb-patterns-resilience for resilience patterns (retry, circuit breaker, rate limiting)
• /pb-patterns-async for async/concurrency patterns
• /pb-patterns-db for database patterns
• /pb-patterns-distributed for distributed system patterns

Ready to review your code before committing? → Use /pb-cycle for self-review and peer review

Ready to commit your changes? → Use /pb-commit to create atomic, well-formatted commits

Ready to create a pull request? → Use /pb-pr for streamlined PR creation

Need help with writing tests? → Use /pb-testing for testing philosophy and patterns

I’m reviewing code…

Reviewing a PR and need a structured approach? → Use /pb-cycle (peer review perspective) for architecture and correctness

Need to check security? → Use /pb-security for security checklist (quick, standard, or deep)

Need to check logging standards? → Use /pb-logging for structured logging validation

Need to check test coverage and quality? → Use /pb-review-tests for test suite quality review

Is this user-facing code or product change? → Use /pb-review-product for product alignment review

Doing a comprehensive code review? → Use /pb-review-hygiene for code quality and maintainability

Is this a microservice change? → Use /pb-review-microservice for service design and contract review

I’m preparing for release…

Ready to release to production? → Use /pb-release for pre-release checks and deployment readiness

Need to plan deployment strategy? → Use /pb-deployment to choose strategy (blue-green, canary, rolling)

Doing final code review before release? → Use /pb-release for senior engineer final review

Is this a major release? → Use /pb-review for comprehensive multi-perspective audit

I’m dealing with production issues…

Production is down or degraded? → Use /pb-incident for rapid assessment and mitigation

Need to monitor system behavior? → Use /pb-observability for monitoring, logging, tracing setup

After incident is resolved, need to analyze? → Use /pb-incident again for comprehensive post-mortem analysis

I’m doing architecture or planning work…

Planning a major feature or release? → Use /pb-plan to lock scope and define success criteria

Documenting an architectural decision? → Use /pb-adr for Architecture Decision Records

Need performance guidance? → Use /pb-performance for optimization and profiling

I’m working on team or organizational things…

Onboarding a new team member? → Use /pb-onboarding for structured onboarding process

Doing a knowledge transfer session? → Use /pb-knowledge-transfer for KT preparation

Want to do team retrospective or feedback? → Use /pb-team for team dynamics and growth

Writing daily standup for distributed team? → Use /pb-standup for async standup template

I’m working on repository or documentation…

Setting up a new project? → Use /pb-repo-init to initialize structure

Need to organize/clean up project directory? → Use /pb-repo-organize for repository cleanup

Writing or rewriting README? → Use /pb-repo-readme for compelling README guidance

Creating GitHub About section? → Use /pb-repo-about for GitHub presentation

Writing a technical blog post? → Use /pb-repo-blog for blog post guidance

Want to do all repository improvements at once? → Use /pb-repo-enhance for full suite

I’m setting standards or frameworks…

Need to understand the SDLC framework? → Use /pb-guide for full 11-phase SDLC with quality gates

Setting team standards and principles? → Use /pb-standards for coding standards and collaboration norms

Need templates for commits, PRs, or reviews? → Use /pb-templates for reusable templates

Need to document how this project works? → Use /pb-context for project context template

Need to write technical documentation? → Use /pb-documentation for technical writing guidance

Scenario-Based Flowchart

START
│
├─ "I'm starting something new"
│  ├─ "Entire project?" → /pb-plan → /pb-repo-init
│  ├─ "Feature/bug?" → /pb-start
│  └─ "Resuming?" → /pb-resume
│
├─ "I'm developing"
│  ├─ "Need patterns?" → /pb-patterns-*
│  ├─ "Ready to review?" → /pb-cycle
│  ├─ "Ready to commit?" → /pb-commit
│  ├─ "Ready to PR?" → /pb-pr
│  └─ "Need tests?" → /pb-testing
│
├─ "I'm reviewing code"
│  ├─ "Architecture?" → /pb-cycle
│  ├─ "Security?" → /pb-security
│  ├─ "Tests?" → /pb-review-tests
│  ├─ "Product fit?" → /pb-review-product
│  ├─ "Logging?" → /pb-logging
│  └─ "Full review?" → /pb-review-hygiene
│
├─ "I'm releasing"
│  ├─ "Pre-release?" → /pb-release
│  ├─ "How to deploy?" → /pb-deployment
│  └─ "Final check?" → /pb-release
│
├─ "Production issue"
│  ├─ "Incident?" → /pb-incident
│  └─ "Monitoring?" → /pb-observability
│
├─ "Architecture/Planning"
│  ├─ "Lock scope?" → /pb-plan
│  ├─ "Document decision?" → /pb-adr
│  └─ "Optimize?" → /pb-performance
│
├─ "Team/Org"
│  ├─ "Onboarding?" → /pb-onboarding
│  ├─ "Knowledge transfer?" → /pb-knowledge-transfer
│  ├─ "Team health?" → /pb-team
│  └─ "Daily standup?" → /pb-standup
│
└─ "Repository/Docs"
   ├─ "New project?" → /pb-repo-init
   ├─ "Organize?" → /pb-repo-organize
   ├─ "README?" → /pb-repo-readme
   ├─ "GitHub about?" → /pb-repo-about
   ├─ "Blog post?" → /pb-repo-blog
   └─ "Full polish?" → /pb-repo-enhance

By Frequency

Daily

• /pb-resume - Get context
• /pb-cycle - Code and review
• /pb-standup - Team standup
• /pb-commit - Create commits
• /pb-context - Refresh project knowledge

Per Feature

• /pb-plan - Lock scope
• /pb-start - Create branch
• /pb-testing - Add tests
• /pb-security - Security gate
• /pb-pr - Create pull request
• /pb-commit - Logical commits

Per Release

• /pb-release - Pre-release checks
• /pb-deployment - Choose strategy
• /pb-release - Final review

Monthly

• /pb-review-hygiene - Code quality
• /pb-review-tests - Test coverage
• /pb-logging - Logging standards

Quarterly

• /pb-review-hygiene - Tech debt
• /pb-review-product - Product fit
• Team retrospective

Occasionally

• /pb-adr - Major decisions
• /pb-patterns-* - Design decisions
• /pb-performance - Optimization
• /pb-incident - Production issues
• /pb-observability - Monitoring setup
• /pb-onboarding - New team members
• /pb-knowledge-transfer - Knowledge transfer
• /pb-team - Team dynamics

One-Time

• /pb-repo-init - New project
• /pb-repo-organize - Cleanup
• /pb-repo-readme - Write README
• /pb-repo-about - GitHub about
• /pb-repo-blog - Tech blog post
• /pb-guide - Learn framework
• /pb-standards - Define standards
• /pb-templates - Create templates
• /pb-context - Document project

By Role

Individual Contributor

• Daily: /pb-resume, /pb-cycle, /pb-standup, /pb-commit
• Per feature: /pb-plan, /pb-start, /pb-testing, /pb-security, /pb-pr
• As needed: /pb-patterns-*, /pb-context

Code Reviewer / Senior Engineer

• Per PR: /pb-cycle, /pb-security, /pb-review-tests, /pb-review-hygiene, /pb-logging
• Per release: /pb-release
• Periodically: /pb-review-product, /pb-review-hygiene

Tech Lead / Architect

• Per feature: /pb-plan, /pb-adr, /pb-patterns-*
• Per release: /pb-release, /pb-deployment, /pb-release
• Periodically: /pb-review, /pb-performance, /pb-observability

Engineering Manager

• Onboarding: /pb-onboarding, /pb-knowledge-transfer
• Team: /pb-team, /pb-standup, team retrospectives
• Strategy: /pb-context, /pb-plan, /pb-adr

DevOps / Infrastructure

• Deployment: /pb-deployment, /pb-release
• Operations: /pb-incident, /pb-observability, /pb-performance
• Setup: /pb-repo-organize, /pb-standards

Product Manager

• Planning: /pb-plan, /pb-context
• Reviews: /pb-review-product
• Documentation: /pb-documentation

Next Steps

• Full Command Reference - See all commands
• Getting Started - Pick a scenario
• Integration Guide - See how commands work together
• FAQ - Common questions

Playbook Integration Guide

Complete reference for how all playbook commands work together to form a unified SDLC framework.

Complete reference for how commands compose into workflows.

Table of Contents

1. Quick Start: Command Selection
2. Command Inventory
3. Specialized Review Personas
4. Workflow Maps
5. Command Clusters
6. Reference Matrix
7. Integration Patterns
8. Common Workflows

Quick Start: Command Selection

By Situation

Starting a new project? → /pb-plan (planning) → /pb-adr (architecture) → /pb-patterns-* (select patterns) → /pb-repo-init (setup)

Implementing a feature? → /pb-start (begin) → /pb-cycle (iterate) → /pb-commit (atomic commits) → /pb-pr (merge)

Implementing a specific todo? → /pb-todo-implement (structured checkpoint-based implementation)

Reviewing code before merge? → /pb-cycle (self-review) → /pb-review-hygiene (peer review) → /pb-security (security review)

Reviewing quality periodically? → /pb-review-tests (monthly) → /pb-review-hygiene (quarterly) → /pb-review-product (product alignment)

Deploying to production? → /pb-release (pre-release checks) → /pb-deployment (strategy selection) → /pb-observability (monitoring)

Incident response? → /pb-incident (assessment + mitigation) → /pb-observability (monitoring) → Post-incident /pb-incident (deep review)

Onboarding new team member? → /pb-onboarding (structured plan) → /pb-knowledge-transfer (KT session) → /pb-guide (SDLC overview)

Quick context recovery? → /pb-resume (get back in context) → /pb-context (refresh decision log)

Command Inventory

CORE FOUNDATION & PHILOSOPHY

These establish baseline understanding and guiding philosophy. Every engineer should know these.

How they work together:

• Read /pb-preamble and /pb-standards to understand philosophy and principles
• Reference /pb-guide for framework (11 phases)
• Use /pb-design-rules for technical design guidance
• Use /pb-templates for format/structure
• Use /pb-documentation for content quality
• Use preamble expansions for specific team contexts
• Use /pb-think for expert-quality collaboration (modes: ideate, synthesize, refine)

SPECIALIZED REVIEW PERSONAS (v2.11.0+)

Five specialized review agents providing complementary perspectives on code, security, reliability, product value, and documentation. Use for deep multi-perspective reviews.

Multi-Perspective Review Workflows (combine complementary personas):

• pb-review-backend - Alex (infrastructure) + Jordan (testing): For backend APIs, services, database operations
• pb-review-frontend - Maya (product) + Sam (documentation): For UI/UX, components, user-facing features
• pb-review-infrastructure - Alex (infrastructure) + Linus (security): For infrastructure code, deployment pipelines, security configs

Persona Composition (how to use together):

CODE REVIEW WORKFLOW WITH PERSONAS:

Single-perspective (for small changes):
  /pb-cycle (self-review)
    └─ Pick ONE persona based on change type:
         ├─ Security issue? → /pb-linus-agent
         ├─ Performance issue? → /pb-alex-infra
         ├─ Feature validation? → /pb-maya-product
         ├─ UI/docs issue? → /pb-sam-documentation
         └─ Test gaps? → /pb-jordan-testing

Multi-perspective (for features):
  /pb-cycle (self-review)
    └─ Use multi-perspective review:
         ├─ Backend: /pb-review-backend (Alex + Jordan parallel)
         ├─ Frontend: /pb-review-frontend (Maya + Sam parallel)
         └─ Infrastructure: /pb-review-infrastructure (Alex + Linus parallel)

Full review (for major releases):
  /pb-cycle (self-review)
    └─ Compose personas in recommended sequence:
       1. Maya (product): Is this solving a real problem?
       2. Parallel: Alex, Jordan, Linus (infrastructure, testing, security)
       3. Sam (documentation): Is this clear to users and maintainers?

When to use which persona:

DEVELOPMENT WORKFLOW

Daily iterative development. Use these multiple times per week.

Development flow:

/pb-start
  ↓
ITERATION LOOP (repeat per task):
  /pb-cycle
    ├─ Self-review
    ├─ /pb-testing (write tests)
    ├─ /pb-standards (check principles)
    └─ Peer review
  /pb-commit (atomic commit)
  ↓
SESSION BOUNDARY (if needed):
  ├─ /pb-pause (end of session: preserve context)
  └─ /pb-resume (next session: recover context)
  ↓
READY TO SHIP:
  /pb-ship (comprehensive workflow)
    ├─ Specialized reviews (cleanup, hygiene, tests, security, docs)
    ├─ Final gate (prerelease)
    ├─ PR creation and peer review
    ├─ Merge and release
    └─ Verification

Key integration points:

• /pb-start → /pb-cycle (iterative development)
• /pb-cycle includes /pb-testing and /pb-standards
• /pb-cycle → /pb-commit (after self-review)
• /pb-pause ↔ /pb-resume (session boundary bookends)
• /pb-ship orchestrates: reviews → PR → merge → release → verify
• /pb-todo-implement provides structured checkpoint-based alternative to direct /pb-cycle workflow

PLANNING & ARCHITECTURE

Technical planning before implementation. Use these once per release.

Planning flow:

/pb-plan (clarify scope)
  ↓
/pb-adr (document decisions)
  ↓
/pb-patterns (select architectural patterns)
  ├─ /pb-patterns-async (if async work needed)
  ├─ /pb-patterns-db (if database changes)
  ├─ /pb-patterns-distributed (if microservices)
  ├─ /pb-patterns-core (core architecture)
  └─ /pb-patterns-resilience (if reliability concerns)
  ↓
/pb-observability (plan monitoring strategy)
/pb-performance (set performance targets)
  ↓
READY FOR IMPLEMENTATION
  ↓
/pb-todo-implement (implement individual todos)
  ↓
/pb-development workflow (pb-start → pb-cycle → pb-commit → pb-pr)

Pattern selection guide:

• Async work? Use /pb-patterns-async (goroutines, channels, job queues, etc.)
• Database layer? Use /pb-patterns-db (pooling, optimization, replication, sharding)
• Core architecture? Use /pb-patterns-core (SOA, event-driven, repository, DTO)
• Reliability? Use /pb-patterns-resilience (circuit breaker, retry, rate limiting)
• Microservices? Use /pb-patterns-distributed (Saga, CQRS, eventual consistency)
• Uncertain? Start with /pb-patterns (overview, then jump to specialized)

REVIEWS & QUALITY

Quality gates at multiple checkpoints. Use these during development, before merge, and periodically.

Code review flow (per PR):

/pb-cycle (self-review)
  ↓
/pb-pr (create pull request)
  ↓
PEER REVIEW GATES:
  /pb-review-hygiene (code quality)
  /pb-security (security checklist)
  /pb-review-tests (test coverage)
  /pb-logging (logging standards)
  /pb-review-product (if user-facing)
  ↓
APPROVED
  ↓
/pb-commit (merge with atomic commit)

Periodic review schedule:

WEEKLY
  ├─ /pb-review-hygiene (spot check)
  └─ /pb-logging (log quality)

MONTHLY
  ├─ /pb-review-tests (test health)
  ├─ /pb-observability (dashboard/alert review)
  └─ /pb-review-product (alignment check)

QUARTERLY
  ├─ /pb-review-hygiene (code cleanup)
  ├─ /pb-review-docs (documentation audit)
  ├─ /pb-security (deep dive)
  └─ /pb-team (team retrospective)

RELEASE
  ├─ /pb-release (final gate)
  ├─ /pb-security (security review)
  └─ /pb-review-microservice (if applicable)

DEPLOYMENT & OPERATIONS

Infrastructure, deployment, and incident response.

Deployment flow:

/pb-release (pre-release checks pass)
  ↓
/pb-deployment (select strategy: blue-green, canary, rolling)
  ↓
Deploy to production
  ↓
/pb-observability (monitor metrics, logs, alerts)
  ├─ All good? Declare victory
  └─ Issues? → /pb-incident (incident response)

Incident flow:

INCIDENT DETECTED
  ↓
/pb-incident (rapid assessment)
  ├─ Severity: P0/P1/P2/P3
  ├─ Choose mitigation:
  │  ├─ Rollback (quickest)
  │  ├─ Hotfix (if rollback not feasible)
  │  └─ Feature disable (safest for toggles)
  │
  ├─ /pb-deployment (if need detailed rollback strategy)
  ├─ /pb-observability (monitor recovery)
  │
  └─ POST-INCIDENT (within 24h)
     ├─ Comprehensive incident review
     ├─ Create /pb-adr if architectural change needed
     └─ Document in /pb-context (decision log)

REPOSITORY MANAGEMENT

Professional repository structure and presentation.

Repository setup flow:

NEW PROJECT:
  /pb-repo-init (initial setup)
    ↓
  /pb-repo-organize (structure directories)
    ↓
  /pb-repo-readme (create README)
    ↓
  /pb-repo-about (set GitHub About)
    ↓
  /pb-repo-blog (write project post)

ENHANCE EXISTING:
  /pb-repo-enhance (one command does all above)

TEAM & CONTINUITY

Knowledge sharing and team development.

Onboarding flow:

NEW TEAM MEMBER JOINS
  ↓
/pb-onboarding (structured 4-phase plan)
  ├─ Phase 1: Preparation
  │  └─ Repo setup, access, dev environment
  ├─ Phase 2: First Day
  │  └─ Welcome, orientation, first task
  ├─ Phase 3: First Week
  │  └─ Pair programming, small tasks, KT sessions
  └─ Phase 4: Ramp-up
     └─ Increasing responsibility, independent work
  ↓
/pb-knowledge-transfer (actual KT session)
  ↓
/pb-guide (SDLC overview and reference)
  ↓
/pb-context (project context and decision log)

Team health flow:

MONTHLY/QUARTERLY
  ↓
/pb-team (team retrospective)
  ├─ Team health check
  ├─ Feedback loops
  ├─ Learning culture
  └─ Growth opportunities
  ↓
Create action items for improvement

REFERENCE & CONTEXT

Project working context and decision log.

Context usage:

CONTEXT REFRESH
  ↓
/pb-context (read current focus, decisions, architecture)
  ↓
Then:
  ├─ Starting work → /pb-start
  ├─ Resuming work → /pb-resume
  ├─ Making decision → Document in /pb-context
  └─ Understanding architecture → /pb-adr

Workflow Maps

Workflow 1: Complete Feature Delivery

PRE-DEVELOPMENT
├─ /pb-plan               ← Clarify scope
├─ /pb-adr                ← Document architecture
├─ /pb-patterns-*         ← Select patterns
├─ /pb-observability      ← Plan monitoring
└─ /pb-performance        ← Set targets

IMPLEMENTATION (iterative daily)
├─ /pb-start              ← Create branch
│
├─ FOR EACH TASK:
│  └─ ITERATION LOOP
│     ├─ /pb-cycle        ← Self-review + peer review
│     │  ├─ /pb-testing   ← Write tests
│     │  ├─ /pb-standards ← Check principles
│     │  ├─ /pb-security  ← Security check
│     │  └─ Refine based feedback
│     │
│     └─ /pb-commit       ← Atomic commit
│
└─ Repeat for each task

CODE REVIEW
├─ /pb-pr                 ← Create pull request
├─ /pb-review-hygiene        ← Code quality
├─ /pb-review-tests       ← Test coverage
├─ /pb-logging            ← Logging standards
├─ /pb-security           ← Security review
├─ /pb-review-product     ← Product alignment (if user-facing)
└─ Approve / Request changes

PRE-RELEASE
├─ /pb-release            ← Release checklist
├─ /pb-release  ← Senior engineer final gate
├─ /pb-deployment         ← Choose deployment strategy
└─ /pb-observability      ← Verify monitoring ready

DEPLOYMENT
├─ Execute deployment (blue-green/canary/rolling)
├─ /pb-observability      ← Monitor metrics
└─ POST-DEPLOYMENT
   ├─ Verify in production
   └─ If issues → /pb-incident

END

Workflow 2: Planning & Architecture

START (New Release/Feature)
├─ /pb-plan                  ← Lock scope
├─ /pb-adr                   ← Document decisions
├─ /pb-patterns              ← Overview of available patterns
│  ├─ /pb-patterns-async     ← If async/concurrency needed
│  ├─ /pb-patterns-db        ← If database changes
│  ├─ /pb-patterns-distributed ← If microservices
│  └─ /pb-patterns-core      ← If core architecture
├─ /pb-observability         ← Plan monitoring strategy
├─ /pb-performance           ← Set performance targets
└─ /pb-deprecation           ← If removing/deprecating existing

IMPLEMENTATION
└─ /pb-todo-implement        ← Structured implementation by todo

Workflow 3: Incident Response

INCIDENT DETECTED
├─ /pb-incident              ← Rapid assessment
│  ├─ Assess severity (P0/P1/P2/P3)
│  ├─ Choose mitigation:
│  │  ├─ Rollback
│  │  ├─ Hotfix
│  │  └─ Feature disable
│  └─ Communicate status
│
├─ /pb-deployment            ← If need detailed rollback
├─ /pb-observability         ← Monitor recovery
│
└─ POST-INCIDENT (within 24h)
   ├─ Comprehensive review
   ├─ Root cause analysis
   ├─ /pb-adr                ← If architectural fix needed
   ├─ Create action items
   └─ Document in /pb-context

PREVENT REPEAT
├─ /pb-cycle                 ← Implement prevention fixes
├─ /pb-testing               ← Add regression tests
└─ /pb-observability         ← Improve alerting

Workflow 4: Team Onboarding

NEW TEAM MEMBER JOINS
├─ /pb-onboarding            ← Structured 4-phase plan
│  ├─ Phase 1: Preparation   ← Setup, access, dev env
│  ├─ Phase 2: First Day     ← Welcome, orientation
│  ├─ Phase 3: First Week    ← Pair programming, KT
│  └─ Phase 4: Ramp-up       ← Independent work
│
├─ /pb-knowledge-transfer    ← KT session execution
├─ /pb-guide                 ← SDLC overview
├─ /pb-standards             ← Working principles
├─ /pb-context               ← Project context
├─ /pb-adr                   ← Architecture decisions
└─ /pb-patterns              ← Design patterns

CONTINUOUS DEVELOPMENT
├─ /pb-start                 ← Start feature work
├─ /pb-cycle                 ← Iterate with feedback
└─ /pb-team                  ← Ongoing feedback and growth

Workflow 5: Periodic Quality Reviews

WEEKLY
├─ /pb-review-hygiene           ← Code quality spot check
└─ /pb-logging               ← Log quality check

MONTHLY
├─ /pb-review-tests          ← Test suite health
├─ /pb-observability         ← Dashboard and alert tuning
└─ /pb-review-product        ← Product alignment

QUARTERLY
├─ /pb-review-hygiene        ← Code cleanup and deps
├─ /pb-review-docs           ← Documentation audit
├─ /pb-security              ← Security deep dive
└─ /pb-team                  ← Team retrospective

RELEASE
├─ /pb-release     ← Final release gate
├─ /pb-security              ← Security review
└─ /pb-review-microservice   ← If applicable

Command Clusters: Groups That Work Together

Cluster 1: Core Foundation

Commands: pb-guide, pb-standards, pb-templates, pb-context Purpose: Establish baseline understanding and discipline Frequency: Reference constantly; update /pb-context periodically Who: Every engineer

Cluster 2: Daily Development

Commands: pb-start, pb-cycle, pb-pause, pb-resume, pb-commit, pb-ship, pb-pr, pb-testing Purpose: Iterative feature development with quality gates, session management, and shipping Frequency: Use multiple times per week per feature Who: All developers

Cluster 3: Planning & Architecture

Commands: pb-plan, pb-adr, pb-patterns (+ 4 specialized), pb-observability, pb-performance Purpose: Design systems before implementation Frequency: Once per release or major feature Who: Tech leads, architects, senior engineers

Cluster 4: Checkpoint-Based Implementation

Commands: pb-plan → pb-todo-implement → pb-cycle Purpose: Structured implementation with checkpoints before full code review Frequency: For major features or refactoring Who: Developers with checkpoint-based approval preference

Cluster 5: Code Review & Quality

Commands: pb-review-*, pb-security, pb-logging, pb-testing Purpose: Multiple perspectives on quality Frequency: Every PR, periodic reviews, pre-release Who: All developers, leads, security team

Cluster 6: Production Safety

Commands: pb-deployment, pb-incident, pb-observability, pb-release Purpose: Safe production deployment and incident response Frequency: Every release, during incidents Who: SREs, DevOps, on-call engineers

Cluster 7: Repository Management

Commands: pb-repo-init, pb-repo-organize, pb-repo-readme, pb-repo-about, pb-repo-blog, pb-repo-enhance Purpose: Professional repository structure and presentation Frequency: Project start, periodic enhancement Who: Tech leads, project owners

Cluster 8: Knowledge & Continuity

Commands: pb-knowledge-transfer, pb-onboarding, pb-team, pb-documentation Purpose: Preserve and share knowledge Frequency: Team transitions, regular intervals Who: Mentors, managers, all engineers

Cluster 9: Thinking Partner

Commands: pb-think Purpose: Self-sufficient expert-quality collaboration Frequency: Throughout development for complex questions, ideation, synthesis Who: All engineers

Thinking Partner Stack:

/pb-think mode=ideate     → Explore options (divergent)
/pb-think mode=synthesize → Combine insights (integration)
/pb-preamble              → Challenge assumptions (adversarial)
/pb-plan                  → Structure approach (convergent)
/pb-adr                   → Document decision (convergent)
/pb-think mode=refine     → Refine output (refinement)

Reference Matrix: Which Commands Work Together

By Incoming References

Most Referenced (critical hub):

• pb-guide: 25+ references (master framework)
• pb-standards: 15+ references (working principles)
• pb-cycle: 10+ references (core development loop)
• pb-testing: 8+ references (quality verification)
• pb-security: 7+ references (quality gate)

Well-Referenced (important workflow nodes):

• pb-adr, pb-deployment, pb-incident, pb-observability, pb-review-hygiene (5-9 references each)

Moderately Referenced (specialized/optional):

• pb-documentation, pb-pr, pb-commit, pb-patterns-* (2-4 references each)

Under-Referenced (isolation issues):

• pb-resume: 0 references (should integrate with pb-start, pb-context)
• pb-standup: 0 references (should integrate with pb-standards, pb-context)

By Category Connections

Core → Everything

• All 44 other commands reference pb-guide and/or pb-standards

Development → Planning

• pb-start → pb-plan (for major features)
• pb-cycle → pb-testing
• pb-cycle → pb-standards
• pb-cycle → pb-security

Planning → Development

• pb-plan → pb-todo-implement
• pb-adr → pb-start (architectural context)
• pb-patterns → pb-cycle (pattern selection)

Development → Review

• pb-cycle → pb-review-hygiene
• pb-commit → pb-review-tests
• pb-pr → pb-review-product

Review → Deployment

• pb-review-hygiene → pb-release (readiness gate)
• pb-security → pb-release
• pb-release → pb-deployment

Deployment → Observability

• pb-deployment → pb-observability
• pb-incident → pb-observability
• pb-observability → pb-incident (feedback loop)

Integration Patterns

Pattern 1: Tiered Complexity

Commands often provide multiple depths:

QUICK (5-15 min)
├─ /pb-security quick checklist (top issues)
├─ /pb-testing unit test patterns
└─ /pb-incident rapid response

STANDARD (20-30 min)
├─ /pb-security standard checklist (20 items)
├─ /pb-testing unit + integration
└─ /pb-incident with escalation

DEEP (1+ hour)
├─ /pb-security deep dive (threat modeling)
├─ /pb-testing E2E + load testing
└─ /pb-incident comprehensive review

Choose based on feature tier (see pb-guide for XS/S/M/L)

Pattern 2: Workflow Sequences

Commands are ordered for maximum clarity:

/pb-plan → /pb-adr → /pb-patterns → /pb-todo-implement → /pb-cycle → /pb-pr → /pb-review-* → /pb-release

Each feeds into the next with clear handoffs.

Pattern 3: “Related Commands” Sections

Most commands include this section showing:

• Prerequisites (what to do before)
• Complementary commands (what to use alongside)
• Next steps (what to do after)

Use these sections for guidance.

Pattern 4: Categories Map to Workflow Phases

PLANNING PHASE → /pb-plan, /pb-adr, /pb-patterns, /pb-performance, /pb-observability
DEVELOPMENT PHASE → /pb-start, /pb-cycle, /pb-commit, /pb-pr, /pb-testing, /pb-todo-implement
REVIEW PHASE → /pb-review-*, /pb-security, /pb-logging
DEPLOYMENT PHASE → /pb-release, /pb-deployment
OPERATIONS PHASE → /pb-incident, /pb-observability
TEAM PHASE → /pb-onboarding, /pb-team, /pb-knowledge-transfer
REPO PHASE → /pb-repo-*, /pb-documentation

Common Workflows: Step-by-Step

Scenario 1: Feature Request from Product

STEP 1: Planning
├─ Read /pb-plan (lock scope)
├─ Read /pb-adr (document architecture)
├─ Choose from /pb-patterns-* (select patterns)
└─ Review /pb-observability (plan monitoring)

STEP 2: Implementation
├─ /pb-start (create feature branch)
├─ LOOP: /pb-cycle (iterate)
│  ├─ Code changes
│  ├─ /pb-testing (add tests)
│  ├─ Self-review
│  └─ Peer review feedback
├─ /pb-commit (atomic commits)
└─ /pb-pr (create pull request)

STEP 3: Code Review
├─ /pb-review-hygiene (code quality)
├─ /pb-review-product (product alignment)
├─ /pb-security (security review)
├─ /pb-review-tests (test coverage)
└─ Approve / Merge

STEP 4: Release Preparation
├─ /pb-release (pre-release checks)
├─ /pb-release (senior review)
├─ /pb-deployment (choose strategy)
└─ /pb-observability (verify monitoring)

STEP 5: Deployment
├─ Execute deployment
├─ Monitor with /pb-observability
└─ Verify in production

Scenario 2: Bug Fix with Incident

STEP 1: Incident Response
├─ /pb-incident (assess severity)
├─ Choose mitigation (rollback/hotfix/disable)
├─ Execute mitigation
└─ Communicate status

STEP 2: Implement Fix
├─ /pb-start (create hotfix branch)
├─ Make minimal fix
├─ /pb-testing (add regression test)
└─ /pb-cycle (review)

STEP 3: Code Review
├─ /pb-cycle (fast-track review)
├─ /pb-security (safety check)
└─ Approve / Merge

STEP 4: Verification
├─ Deploy hotfix
├─ Monitor with /pb-observability
└─ Verify recovery

STEP 5: Post-Incident
├─ /pb-incident (comprehensive review)
├─ Root cause analysis
├─ /pb-adr (if architectural fix needed)
└─ Document in /pb-context

Scenario 3: Refactoring Large Component

STEP 1: Planning
├─ /pb-plan (refactoring scope)
├─ /pb-adr (new architecture decision)
├─ /pb-patterns (design patterns)
└─ /pb-performance (performance targets)

STEP 2: Implementation Phases
├─ Phase 1:
│  └─ /pb-todo-implement (checkpoint-based)
│     ├─ REFINE: Analyze codebase
│     ├─ PLAN: Outline refactoring steps
│     └─ IMPLEMENT: Execute checkpoint-by-checkpoint
├─ Phase 2:
│  └─ /pb-todo-implement (next component)
└─ Continue for each component

STEP 3: Code Review
├─ /pb-review-hygiene (architecture alignment)
├─ /pb-review-tests (regression test coverage)
├─ /pb-security (if security implications)
└─ Approve / Merge

STEP 4: Quality Verification
├─ /pb-observability (performance metrics)
├─ /pb-review-tests (no regressions)
└─ /pb-team (document learnings)

Scenario 4: New Team Member Joins

WEEK 0: Preparation (Before they arrive)
├─ /pb-onboarding (prepare environment)
├─ /pb-repo-organize (ensure clear structure)
└─ /pb-documentation (update docs)

DAY 1: First Day
├─ Follow /pb-onboarding Phase 2
├─ Dev environment setup
├─ Team introductions
└─ High-level project overview

WEEK 1: First Week
├─ /pb-knowledge-transfer (KT session)
├─ /pb-guide (SDLC overview)
├─ /pb-adr (architecture decisions)
├─ /pb-standards (working principles)
└─ Small task with pair programming

WEEK 2-4: Ramp-up
├─ Increasing task complexity
├─ Independent work with feedback
├─ /pb-cycle (code review feedback)
└─ /pb-team (feedback and support)

ONGOING: Growth
├─ /pb-cycle (iterate on features)
├─ /pb-standards (reinforce principles)
└─ /pb-team (regular feedback)

Summary: Playbook as Unified System

Core Principle

The commands form a unified SDLC framework. Use them in combination, not isolation:

ISOLATED:
[NO] /pb-cycle alone
[NO] /pb-security alone
[NO] /pb-testing alone
[NO] /pb-observability alone

EFFECTIVE:
[YES] /pb-cycle WITH /pb-testing, /pb-standards, /pb-security
[YES] /pb-plan WITH /pb-adr, /pb-patterns, /pb-observability
[YES] /pb-incident WITH /pb-observability, /pb-deployment, /pb-adr
[YES] /pb-onboarding WITH /pb-knowledge-transfer, /pb-guide, /pb-standards

Key Relationships

1. Foundation → All work

   • pb-guide, pb-standards, pb-templates, pb-context

2. Plan → Implement

   • pb-plan → pb-adr → pb-patterns → pb-observability → pb-todo-implement

3. Develop → Review → Release

   • pb-start → pb-cycle → pb-commit → pb-pr → pb-review-* → pb-release

4. Safety → Observability → Incident

   • pb-deployment → pb-observability → pb-incident

5. Knowledge → Growth

   • pb-onboarding → pb-knowledge-transfer → pb-team → pb-documentation

When to Use Each Command

You’ll know you need a command when:

• /pb-guide: You’re unsure how a phase works
• /pb-standards: You’re making a decision on scope or quality
• /pb-plan: You’re starting a major feature/release
• /pb-adr: You’ve made an architectural decision
• /pb-patterns-*: You’re designing a system component
• /pb-start: You’re beginning feature work
• /pb-cycle: You’ve coded something and need review
• /pb-commit: You’re creating a commit message
• /pb-pr: You’re merging code
• /pb-testing: You’re writing tests
• /pb-todo-implement: You want checkpoint-based approval
• /pb-review-*: You need quality perspective
• /pb-security: You need to verify security
• /pb-deployment: You’re preparing production deploy
• /pb-incident: Production is broken
• /pb-observability: You need to monitor/trace
• /pb-onboarding: Someone new is joining
• /pb-team: Team health needs attention
• /pb-repo-*: Repository structure needs improvement
• /pb-context: You need quick context refresh

This guide is the map. Use it to navigate the playbook as an integrated system.

Using Playbooks with Other Agentic Tools

These playbooks were designed for Claude Code. They’re portable.

The underlying patterns work with any agentic development tool - different framework, same thinking.

The Three Layers

Layer 1: Principles (100% Portable)

What it is: How you think together and what you build

• Preamble: Challenge assumptions. Prefer correctness over agreement. Think like peers.
• Design Rules: Clarity, Simplicity, Resilience, Extensibility. 17 classical principles.
• BEACONs: 9 guiding principles for code quality, decision-making, team dynamics

Portability: Works in any tool, any language, any team. These are universal.

Usage: Read /pb-preamble and /pb-design-rules. Apply them in your workflow, whatever tool you use.

Layer 2: Commands (95% Portable)

What it is: 100 structured prompts covering full SDLC (planning → dev → review → ship)

• Command content: Universal. Patterns, questions, checklists don’t care about your tool.
• Invocation: Tool-specific. Claude Code users type /pb-start. You adapt to your tool.
• Metadata: Structured (Resource Hint, When to Use, Related Commands, etc.) - same everywhere.

Portability: Copy the Markdown files. Reference them however your tool surfaces prompts.

How to use:

1. Clone the repo: git clone https://github.com/vnykmshr/playbook.git
2. Read commands as Markdown: cat commands/development/pb-start.md
3. Apply the pattern to your workflow
4. Adapt the invocation to your tool

Example:

Claude Code user:

/pb-start "add user authentication"

You (with another tool):

• Open commands/development/pb-start.md in your editor
• Copy the questions from “Phase 1: Scope”
• Ask your tool to answer them
• Proceed with the ritual

Layer 3: Integration (Tool-Specific)

What it is: How commands surface and integrate with your development environment

Claude Code features:

• Skills: /pb-start invokes directly in conversation
• Keybindings: Fast shortcuts to common commands
• Context management: Automatic pause/resume, working context snapshots
• Hooks: Advisory warnings when context gets large
• Status line: Token usage visibility

You (with another tool): Adapt this layer to your tool’s capabilities.

Examples:

Adaptation Checklist

1. Adopt Principles (Zero Work)

Read and internalize:

• /pb-preamble - How your team thinks together
• /pb-design-rules - What you build
• Apply them to: planning, code review, decision-making, incident response

2. Adopt Commands (Low Work)

For each command category you care about:

• Read the Markdown file
• Understand the phases/checkpoints
• Adapt the ritual to your workflow
• Document how your team invokes it (alias, script, manual, etc.)

Start with these core commands:

• /pb-start - Begin work (scoping ritual)
• /pb-cycle - Self-review and iteration
• /pb-commit - Atomic, well-explained commits
• /pb-review-hygiene - Code quality checklist
• /pb-plan - Focus area planning

3. Adapt Integration (Medium Work)

Build tool-specific adapters:

• How do you invoke playbook commands? (CLI, web UI, editor plugin, manual read, etc.)
• Where do you store preferences/context? (Config files, environment, database, etc.)
• How do you get reminders? (Hooks, alerts, dashboard, manual checklist, etc.)
• How do you preserve context between sessions? (Git, files, tool-native storage, etc.)

Concrete Adaptation Examples

Example 1: Using with CLI Tool + Git

Tool: Command-line based, Git-aware

Adaptation:

# 1. Alias to playbook commands
alias pb-start='cat ~/playbook/commands/development/pb-start.md'
alias pb-cycle='cat ~/playbook/commands/development/pb-cycle.md'

# 2. Create a wrapper script for scope questions
# ~/bin/start-work.sh
#!/bin/bash
echo "=== Scope your work ==="
read -p "What are you building? " description
read -p "Why does this matter? " rationale
# ... (ask remaining questions from pb-start)
git switch -c feature/$description

# 3. Use Git hooks for checkpoints
# .git/hooks/pre-commit
# Verify: has atomic change (one concern)
# Verify: no debug artifacts
# Run: lint, tests

# 4. Environment-based context
# Set these in your shell profile
export PB_WORKING_CONTEXT="$HOME/project/context.md"
export PB_PRINCIPLES="$HOME/playbook/docs/preamble.md"

Invocation:

# Start work
start-work.sh

# During development
git diff  # See your atomic change

# Before commit
cat ~/playbook/commands/development/pb-commit.md  # Remind yourself of guidelines

# Code review
cat ~/playbook/commands/reviews/pb-review-hygiene.md  # Copy the checklist

Example 2: Using with Web-Based Tool

Tool: Web-based IDE or cloud development platform

Adaptation:

1. Import playbook as documentation
   - Create wiki/docs project in your tool
   - Copy all commands as pages
   - Link navigation between related commands

2. Create templates
   - PR template: Copy from /pb-pr guidance
   - Commit template: Copy from /pb-commit guidance
   - Issue template: Copy from /pb-plan phases

3. Dashboard/checklist
   - Pin key commands (Preamble, Design Rules, pb-cycle)
   - Create quick-reference card for your team

4. Workflows
   - Create automation that suggests relevant command
   - Example: "PR created → suggest /pb-review-code checklist"

Example 3: Using with Agent-Specific Tool (e.g., different LLM provider)

Tool: Different AI provider with agent/tool APIs

Adaptation:

1. Load commands as tool definitions
   - Playbook commands → Tool/function definitions
   - Metadata becomes tool descriptions
   - Phases become sequential steps

2. Example: /pb-start as a tool
   Tool: start-work
   Description: "Scope development work. Ask discovery questions."
   Input: Project description
   Output: Scope statement, success criteria, phases
   Next: Suggest /pb-plan if multi-phase

3. Chain tools together
   start-work → plan-focus → implement → review → commit → ship

4. Preserve context differently
   - Each message includes: current phase, why it matters, next checkpoint
   - Agent chooses which command/tool to invoke next

What Doesn’t Translate (And Why)

1. Skill Invocation (/pb-start)

Claude Code surface commands as skills. Your tool has different affordances.

Solution: Use the closest equivalent (alias, CLI subcommand, web form, manual reference).

2. Keybindings

Claude Code offers keyboard shortcuts. Your tool may not support them, or works differently.

Solution: Use your tool’s native shortcuts, or create a workflow guide for your team.

3. Context Bar (Token Usage)

Claude Code shows token usage in a status line. Different tools have different capabilities.

Solution: Use your tool’s native monitoring (IDE metrics, logs, API dashboards).

4. Hooks (Advisory Warnings)

Claude Code warns when context is approaching limits. Your tool may not have this concept.

Solution: Manual checkpoint: “Every 1 hour, review context size” or use your tool’s alerts.

Quick Reference: Command Mapping

Principles Over Rules

The playbook is built on principles, not rules.

• Principle: “Atomic changes are easier to review and revert”

  • Claude Code: Enforce via commit templates
  • Your tool: Enforce via PR naming convention
  • Manual: Document the expectation, review for it

• Principle: “Code quality gates prevent regressions”

  • Claude Code: Automatic lint/test checks
  • Your tool: CI/CD pipeline
  • Manual: Pre-commit checklist

Bottom line: Adapt the mechanism (how you enforce it) to your tool. Keep the principle (why it matters) universal.

Getting Started (Choose Your Path)

Path A: I Use Claude Code

You’re all set. Commands are available as skills. Read the integration guide to understand workflows.

Path B: I Use Another Tool, Want Full Integration

1. Read /pb-preamble and /pb-design-rules (15 min)
2. Clone the playbook repo
3. Create adapters for your tool (1-2 hours)
4. Document your team’s workflow (30 min)
5. Start using commands for your next project

Path C: I Want to Explore First

1. Read /pb-preamble and /pb-design-rules
2. Pick one command (e.g., /pb-plan)
3. Read it as Markdown
4. Use it manually for your next project
5. Iterate and adapt as you learn

FAQ

Q: Will using these commands without Claude Code be awkward?

A: Not at all. The patterns are the point. How you invoke them is implementation detail. Many teams use similar rituals without special tooling.

Q: Can I modify commands for my team?

A: Yes. Fork the repo, adapt to your needs, share with your team. The principles are stable; implementation is flexible.

Q: Is there a “right” way to integrate with my tool?

A: No. Whatever makes sense for your team. Some teams use aliases and Markdown. Some build dashboards. Some print them and post them on the wall. All valid.

Q: Will these playbooks stay useful as tools evolve?

A: Yes. The principles (Preamble, Design Rules) never change. Commands may be refreshed quarterly. Integration mechanisms (how you invoke them) are tool-specific and always adaptable.

Start here: Read /pb-preamble and /pb-design-rules. Everything else flows from there.

Playbook in Action

The standard development cycle using playbook commands.

Development Cycle

/pb-start "what you're building"
  → code
/pb-review
  → automatic quality gate, auto-commit
/pb-pr
  → peer review

Command Quick Reference

Common Scenarios

Adding a Feature

/pb-start "feat: add user profiles"
# write code, write tests
/pb-review
/pb-pr

Fixing a Bug

/pb-start "fix: email validation"
# write failing test, fix code, verify test passes
/pb-review
/pb-pr

Addressing Review Feedback

# make changes based on feedback
/pb-review
# auto-pushes to existing PR

See /pb-guide for the full SDLC framework.

Collaboration Preamble: Thinking Like Peers

This anchors how we think and work together. Not a process, but a mindset that every other playbook command assumes you bring.

Resource Hint: opus - Foundational philosophy; requires deep reasoning about collaboration dynamics.

When to Use

• Setting team culture norms at the start of a project or engagement
• Resolving collaboration friction (deference, silence, performative agreement)
• Onboarding new team members to the “how we think” foundation
• Referencing when other playbooks cite /pb-preamble thinking

I. The Core Anchor

Challenge assumptions. Prefer correctness over agreement. Think like peers, not hierarchies.

Why this matters:

• Bad ideas multiply when left unchallenged
• Politeness kills progress
• Hierarchy stifles honest thinking
• Senior engineers are wrong more often than you’d think

Without this anchor, teams default to performative agreement, risk-averse consensus, and deference over clarity. This preamble is the antidote.

What “Thinking Like Peers” Means

Hierarchy thinking:

• Junior person defers to senior person
• Senior person decides; others execute
• Disagreement is disrespect
• Silence protects relationships
• Status informs correctness

Peer thinking:

• All perspectives are examined equally
• Best idea wins, informed by context and seniority
• Disagreement is professional
• Silence is complicity in bad decisions
• Context and seniority inform but don’t overrule evidence

This doesn’t mean ignoring experience or authority. It means authority is earned through good reasoning, not just position.

I.5 Preamble + Design Rules: Complete Philosophy

The preamble answers: HOW do teams think together?

• Challenge assumptions
• Prefer correctness over agreement
• Think like peers, not hierarchies
• Use transparent reasoning

Design rules answer: WHAT do we build?

• See /pb-design-rules for the 17 technical principles
• Organized into 4 clusters: Clarity, Simplicity, Resilience, Extensibility
• Guide every architectural and technical decision
• Ensure systems that are clear, simple, reliable, and adaptable

Why both matter:

A team with preamble thinking but no design discipline builds wrong things. They collaborate well while making poor technical choices. A team with design rules but no preamble thinking debates endlessly without resolution. They know what good design looks like but can’t decide together.

How they work together:

• Preamble thinking enables design discipline: When teams challenge assumptions openly, they can discuss design rules without defensiveness
• Design rules anchor preamble thinking: When teams have shared design principles, they have concrete ground to stand on when challenging ideas
• Both together: Better decisions, faster execution, systems that scale

Every command in the playbook assumes both: peer thinking (preamble) and sound design (design rules).

II. Four Principles

Principle A: Correctness Over Agreement

Disagree when needed. The goal is getting it right, not maintaining harmony.

• Point out flaws early and directly
• No flattery, no validation for its own sake
• Weak ideas should be called weak
• If something seems risky, say so
• Better a tense 5-minute conversation than a silent problem in production

In practice: “I think this approach is risky because X. Have you considered Y instead?”

Principle B: Critical, Not Servile

Act as a critical peer, not a subordinate seeking approval.

• Challenge premises before accepting tasks
• Question scope, estimates, and assumptions
• Peer-to-peer, not assistant-to-leader
• Assume you have valuable input because you do
• Your hesitation is a data point worth surfacing

In practice: “Before we scope this, I want to surface three assumptions I see. Can we validate them?”

Principle C: Truth Over Tone

Direct, clear language beats careful politeness.

• Explain your reasoning, not just your conclusion
• Offer alternatives with explicit trade-offs
• Assume the other person values critical thinking over tone management
• Short, honest feedback beats long, careful wordsmithing

In practice: “This is simpler, but slower. That one is faster, but more complex. Here’s why I’d pick X for our use case…”

Principle D: Think Holistically

Optimize for outcomes, not just code.

• Consider product, UX, engineering, security, and operations simultaneously
• Question trade-offs across all domains
• Surface hidden costs and technical debt
• One engineer’s elegant solution might create three problems elsewhere
• Think end-to-end: will this scale? Is it secure? Can we operate it?

In practice: “This is architecturally clean, but our ops team can’t monitor it. Can we add observability hooks?”

Principle E: Respect Attention as a Finite Resource

Thinking like peers means respecting each other’s attention.

• Your time is finite. So is everyone else’s. Code that’s hard to understand wastes attention.
• User attention is finite. Systems that demand constant vigilance create friction.
• Operator attention is finite. Systems that hide problems force constant vigilance.
• Clear, calm systems are an act of respect: “I built this thinking about your attention.”

In practice: “This feature is powerful, but it demands constant tweaking. Can we make it self-tuning so operators don’t have to think about it?”

See /pb-calm-design for the complete calm design framework-how to build systems that respect user attention.

II.5 When to Challenge, When to Trust

Preamble doesn’t mean challenge everything. Discernment matters.

Challenge When:

• Assumptions are unstated - “We need microservices” (why? under what constraints?)
• Trade-offs are hidden - “Simple solution” (simple for whom? what’s the cost?)
• Risk is glossed over - “This is production-ready” (have we tested failure modes?)
• Scope is unclear - “Add this feature” (what does done look like?)
• Process is unfamiliar - First time doing something, you don’t understand the reasoning
• Context has changed - “We always do X” (still true? constraints changed?)
• Your expertise applies - You have information others don’t

Trust When:

• Expert has explained reasoning - They’ve shown their thinking, trade-offs are clear
• You lack context - Decision is outside your domain, they have information you don’t
• Time cost exceeds benefit - Challenging a button color wastes more time than it’s worth
• Decision is made, execution is on - Time to align and execute, not re-litigate
• Pattern is proven - “We’ve done this 20 times this way, it works” is data
• You’re learning from them - Better to understand their reasoning than challenge it

The Balance

Best teams oscillate between:

• Healthy challenge (pointing out risks, unstated assumptions)
• Trust-based execution (alignment once decision is made)
• Retrospective learning (why did that work or fail)

Worst teams get stuck in:

• Perpetual debate (never deciding)
• Blind trust (never questioning)
• Post-mortem blame (only questioning after failure)

The goal is: Challenge early, decide clearly, execute aligned.

III. How Other Commands Embed This

Every playbook command assumes you’re reading with this preamble in mind:

• /pb-guide - The framework is a starting point, not dogma. Challenge the tiers, rearrange gates, adapt to your team
• /pb-standards - Principles, not rules. Understand why before following how
• /pb-cycle - Peer review is designed to surface disagreement, not confirm approval
• /pb-adr - Decisions are documented with required alternatives and trade-offs explicitly. Others can challenge the reasoning
• /pb-plan - Scope lock is a negotiation. Challenge estimates, uncover hidden assumptions
• /pb-commit - Clear messages force you to explain why, inviting scrutiny
• /pb-pr - Code review assumes critical thinking from both author and reviewer
• /pb-review-* - All review commands are designed to surface different perspectives and disagreement
• /pb-patterns-* - Trade-offs are always discussed. No pattern is universally right
• /pb-security - Security review explicitly looks for what was missed
• /pb-testing - Tests are designed to catch flawed thinking, not validate it
• /pb-deprecation - Thoughtful decisions require questioning the status quo
• /pb-observability - Multi-perspective thinking: ops, security, product, engineering

The integration: This preamble is the why behind every command. Each command is more powerful when read with this lens.

IV. Examples: What This Looks Like

Example 1: In a Planning Session

Without preamble (common default):

Lead: "We'll build it with async queues."
Team: "Sounds good!" (silent concerns about complexity, maintainability unspoken)
Later: System is hard to debug, two engineers leave, we rewrite it

With preamble:

Lead: "We'll build it with async queues. I'm assuming we have
someone who understands event-driven systems. And that we can monitor it."
Team: "I think assumption 1 is risky. We don't have that expertise.
What about option B: synchronous with background jobs?"
Lead: "That's a fair point. Let me think through the trade-offs..."
Better decision, risks surfaced early, team stays.

What changed: Preamble gave permission to challenge. Assumptions got explicit. Thinking improved.

Example 2: In Code Review

Without preamble:

Reviewer: "Looks good to me!" (notices edge case, says nothing)
Later: Bug in production in that exact edge case

With preamble:

Reviewer: "This works, but I see a potential issue: what happens
when X is null? Have you tested that scenario?"
Author: "Actually, I didn't think about that. Let me add a test."
Code is more robust. Edge case caught early.

What changed: Preamble made challenging the default. Hidden risks surfaced.

Example 3: In Design Discussion

Without preamble:

Lead: "We'll use async pattern A for this."
Engineer: "Actually, pattern B is 40% faster..." (stops, defers instead)
Lead: "Pattern A is final."
Later: System is slow. Engineer regrets not speaking up.

With preamble:

Lead: "We'll use async pattern A. Trade-off: simpler code,
slightly higher latency. Any concerns?"
Engineer: "I think we should use pattern B instead. It's 40% faster.
More complex, but worth it for this use case."
Lead: "You're right. Let's do B."
Better decision. Engineer's thinking was heard.

What changed: Preamble invited challenge with reasoning. Better decision made.

Example 4: In a Security Review

Without preamble:

Security reviewer: "Looks secure to me." (notices SQL injection risk in one place, decides it's "not my job" to challenge the architecture)
Later: Data breach in that exact location

With preamble:

Security reviewer: "This input validation looks fragile. Have you tested what happens with special characters? I'm concerned about SQL injection risk."
Developer: "I didn't think about that. Let me add parameterized queries."
Risk prevented. Architecture improved.

What changed: Preamble made the reviewer responsible for surfacing flaws, not just approving. Critical thinking became the job, not optional.

Example 5: In a Deprecation Decision

Without preamble:

Lead: "We're deprecating the old API."
Team: "Okay." (silently worried about unknown consumers, backwards compatibility, migration path)
Later: Three production incidents from customers still using old API. Emergency support cost $50k.

With preamble:

Lead: "We're deprecating the old API in 6 months."
Engineer: "Before we commit, I want to surface some risks. Do we know all the consumers? What's our migration support plan? What happens to customers who don't upgrade?"
Lead: "Good point. Let me verify that first."
Better plan emerges: 12-month deprecation, migration guide, support window. Fewer surprises.

What changed: Preamble gave permission to surface risks before they became emergencies. Questions asked early saved months of pain.

V. Common Questions

Q: “Doesn’t this feel disrespectful?”

A: Only if you conflate challenge with rudeness. Challenging assumptions respectfully is professional. Disagreement shows you care about getting it right. Silence is disrespect to the team-you’re withholding your best thinking.

Q: “What if I’m wrong in my challenge?”

A: Good. That’s how you learn. The point isn’t that you’re always right; it’s that you think critically. If your challenge doesn’t hold up, explain why, and both of you understand the decision better.

Q: “What about seniority? Doesn’t the senior person decide?”

A: Yes, the senior person makes the final call when there’s disagreement. But they should only do so after genuinely considering the challenge. “Because I said so” is not a rationale. The senior person’s job is to have more context, not final truth.

Q: “How is this different from just ‘speaking up’?”

A: It’s systemic. Without this preamble, speaking up feels risky. Your instinct is to agree. With it, silence feels risky-to quality. It flips the default from “agree unless proven wrong” to “challenge unless it’s clearly rock-solid.”

Q: “What if the team uses this to nitpick everything?”

A: Fair worry. The principle is critical thinking, not obstruction. Challenge the risky assumptions. Challenge the trade-offs. Don’t challenge the color of the button. This requires judgment, which grows with practice.

VI. How to Use This Command

Before Starting Any Other Playbook Command

Read this first. It reframes how you read everything else. When /pb-cycle says “peer review,” it assumes this preamble. When /pb-adr requires alternatives, it’s enforcing this thinking.

Before Joining Any Collaboration

Reference this. Understand that challenges are expected, disagreement is professional, and silence is a failure mode.

When Feeling Uncertain About Speaking Up

Reread Principle C. Your hesitation is what this preamble is designed to overcome. Think truth over tone.

When Leading a Process

Reference this to your team. “This preamble applies to all our work together. I want your best thinking, not your agreement.”

When Receiving Feedback You Disagree With

Remember: they’re operating from this preamble. They’re not being rude; they’re trying to get it right. Respond with the same principle: explain your reasoning, explore the trade-offs, find the better answer together.

VII. Integration: Where This Anchors

This preamble is referenced by:

Core Commands:

• /pb-guide - Scope lock is a collaborative decision, not a decree
• /pb-standards - Collaboration principles section explicitly links to this
• /pb-documentation - Clear writing invites healthy challenge

Development Workflow:

• /pb-cycle - Step 3: Peer Review assumes preamble thinking. Reviewer challenges, author welcomes critical feedback.
• /pb-commit - Clear messages force you to explain why, inviting scrutiny and challenge
• /pb-pr - Code review process assumes critical thinking from both author and reviewer
• /pb-start - Team alignment gate explicitly includes “assumptions are explicit, disagreements surfaced”
• /pb-testing - Tests are designed to catch flawed assumptions, not validate them

Planning & Architecture:

• /pb-plan - Clarify phase assumes peer-level challenge: “Clarify means ask hard questions and challenge assumptions”
• /pb-adr - Alternatives and Rationale sections require explicit reasoning that can be challenged
• /pb-patterns-* - Every pattern guide emphasizes: question if it fits, challenge the costs, explore alternatives
• /pb-performance - “Question assumptions about slowness. Challenge whether optimization is worth the complexity cost.”
• /pb-observability - “Multi-perspective thinking: no single perspective is complete”
• /pb-deprecation - “Challenge whether change is really necessary. Surface impact on users.”

Reviews & Quality:

• /pb-review - Comprehensive review assumes critical perspective from multiple experts
• /pb-review-hygiene - “Challenge architectural choices. Point out duplication and complexity. Surface flaws directly.”
• /pb-review-tests - “Question test assumptions. Challenge coverage claims. Point out flaky or brittle tests.”
• /pb-review-docs - “Find unclear sections, challenge stated assumptions, and surface gaps”
• /pb-security - “Your job is to find what was missed, challenge assumptions about safety, and surface risks”
• /pb-review-product - “Each perspective should challenge the others. Surface disagreements-they surface real problems.”
• /pb-review-microservice - “Question service boundaries. Challenge coupling. Surface design flaws early.”
• /pb-logging - “Logs must reveal assumptions and make failures obvious, not hide them”
• /pb-release - “Challenge readiness assumptions. Surface risks directly. Don’t hide issues at last gate.”

Team & Operations:

• /pb-team - “Psychological safety is directly enabled by preamble thinking. When teams operate from that preamble, challenging assumptions becomes the default.”
• /pb-incident - “During response: be direct about status, challenge assumptions about cause, surface unknowns”
• /pb-standup - “Surface blockers and risks directly. Use preamble thinking: be direct about problems, don’t hide issues to seem productive.”
• /pb-onboarding - “New team members learn this preamble first: challenge assumptions, prefer correctness, think like peers.”

Meta Commands:

• /pb-what-next - Context analysis requires critical perspective
• /pb-knowledge-transfer - Transferring knowledge requires honest discussion

Every command that involves collaboration, decision-making, or review assumes this preamble.

Why This Matters

Teams without this anchor fall into patterns:

• Performative agreement - “Looks good!” without actual critical thought
• Risk-averse consensus - Lowest common denominator wins, not best idea
• Hierarchy over quality - Senior person decides, junior person stays quiet
• Hidden problems - Issues surface in production, not in planning
• Regret and burnout - Team members knew the risk but didn’t speak up

Teams with this preamble:

• Better decisions - Assumptions get surfaced and tested
• Psychological safety - You can disagree without fear
• Faster learning - Mistakes are caught early
• Ownership mindset - You’re responsible for quality, not just execution
• Sustainable pace - Problems don’t surprise you in production

This preamble isn’t nice-to-have. It’s foundational. Everything else in the playbook depends on it.

VIII. When This Goes Wrong: Failure Modes

Failure Mode 1: Argumentative Culture

What it looks like: Team challenges everything. Every decision turns into debate. Nothing gets shipped.

Why it happens:

• Preamble interpreted as “challenge everything, always”
• No distinction between healthy challenge and obstruction
• Judgment about what’s worth challenging never develops

Prevention:

• Emphasize Section II.5: “When to Challenge, When to Trust”
• Use post-mortems to reflect: “Was this debate valuable?”
• Leader models when to stop debating and decide

Failure Mode 2: Leader Dismissal

What it looks like: “I’m challenging your concern, not ignoring it” becomes cover for dismissal.

Why it happens:

• Leader uses preamble language as justification to override concerns
• “Your concern is valid, but I disagree” without genuine engagement
• Pseudo-listening that doesn’t actually consider the challenge

Prevention:

• Leaders must demonstrate they’ve genuinely considered the challenge
• Ask: “Am I actually engaging with this concern or just performing engagement?”
• Team feels free to escalate if dismissal pattern becomes clear

Failure Mode 3: Tone Weaponization

What it looks like: “Just be more direct” becomes code for “shut up and accept it.”

Why it happens:

• Preamble emphasizes “truth over tone”
• Gets misused as “I can say anything harshly and you should accept it”
• Actual rudeness gets justified as “just being direct”

Prevention:

• Truth over tone ≠ Rudeness
• Clarify: “Direct and respectful” is the standard, not “direct and harsh”
• Challenge tone when it’s genuinely unhelpful

Failure Mode 4: Pseudo-Psychological Safety

What it looks like: Team publicly invites challenge but subtly punishes it.

Why it happens:

• Leadership says “disagree with me” but reacts badly when people do
• Preamble becomes theater instead of culture
• People learn safe disagreement is punished in subtle ways (tone, assignment, promotion)

Prevention:

• Leadership must visibly accept challenges and change decisions
• Track patterns: does challenging ever affect promotion/assignment? If yes, you have a problem
• Regular check-in: “Do you feel safe disagreeing with me?” If no, rebuild trust first

Failure Mode 5: Perpetual Indecision

What it looks like: Competing perspectives are all equally valid. Decisions never get made or keep getting reopened.

Why it happens:

• Preamble emphasizes showing trade-offs, all perspectives
• Confusion between “surface all perspectives” and “all perspectives are equally correct”
• Leader afraid to decide, hiding behind “we need more input”

Prevention:

• Decision time has a clock. Debate until then, then decide.
• Decision authority is clear (senior person decides, after hearing challenge)
• Decisions can be revisited if circumstances change, but not constantly

Failure Mode 6: Senior Person Abuse

What it looks like: Junior team member challenges decision. Senior person says “I’ve decided, preamble doesn’t apply to hierarchy.”

Why it happens:

• Preamble is interpreted as “only works among equals”
• Authority sees preamble as threat instead of improvement
• Deliberate misreading: “You’re trying to override my authority”

Prevention:

• Make explicit: Preamble applies across hierarchy
• “Senior person decides” doesn’t mean “senior person isn’t challenged”
• Senior person’s job is to genuinely engage with challenge, not just pretend to

What to Do If You Notice a Failure Mode

1. Name it - “I think we’re in perpetual debate mode. Should we set a decision deadline?”
2. Reference the preamble - “Preamble says to challenge early and decide clearly”
3. Propose the fix - “I suggest we debate this until Friday, then decide Monday”
4. Don’t go silent - If pattern persists, escalate (to leadership, 1-on-1, team retro)

The test: Does your team show the benefits listed in “Why This Matters”? If not, something’s gone wrong and needs addressing.

IX. What’s Next: Philosophy Expansion

This preamble establishes the foundational mindset. Three more parts are being developed to address nuance and context:

Part 2: Async & Distributed Teams (in progress)

• How preamble thinking works in async communication (Slack, GitHub comments, async meetings)
• Timing, tone, and intent in written feedback
• Building trust across distributed teams
• Psychological safety in remote-first cultures

Part 3: Power Dynamics & Psychology (in progress)

• How preamble applies across hierarchies (reporting relationships, performance reviews)
• Dissent escalation: when to accept vs. escalate
• Building toward preamble thinking on teams with low psychological safety
• Authority earned through reasoning, not just position

Part 4: Decision Making & Dissent (planned)

• Decision reversal: when you’ve disagreed, now what?
• Cost-benefit of continuous challenge
• Loyalty after disagreement
• Building toward organizational learning culture

These expansions deepen the philosophy with context-specific guidance while keeping core preamble intact.

Related Commands

• /pb-preamble-async - Async and distributed team collaboration
• /pb-preamble-power - Power dynamics and psychological safety
• /pb-preamble-decisions - Decision making and dissent
• /pb-design-rules - Technical principles (complement to preamble)
• /pb-think - Structured thinking with preamble mindset

Read this before any other command. Reference it when you feel hesitation about speaking up. Build it into your culture from day one.

Preamble Part 2: Async & Distributed Teams

Extending core preamble thinking to asynchronous communication, distributed teams, and remote-first cultures.

Resource Hint: opus - Deep collaboration philosophy applied to async contexts; nuanced reasoning required.

When to Use

• Transitioning a team to remote-first or async-heavy workflows
• Diagnosing communication breakdowns in distributed teams
• Establishing async norms for cross-timezone collaboration

I. The Async Challenge

Core preamble works in real-time: face-to-face conversation, synchronous meetings, immediate feedback. Tone is visible. Intent is clarified. Misunderstandings get resolved in minutes.

Async breaks this:

• No immediate clarification when misunderstood
• Tone disappears in text. Your “direct challenge” reads as harsh
• Time zones mean decisions can’t happen synchronously
• Context is fragmented across threads, messages, documents
• Vulnerability is harder when unobserved
• Trust must be built differently

The risk: Teams retreat to performative agreement because challenge feels even more risky async. Silence increases. Problems hide.

The opportunity: Written communication forces clarity. Challenge must be explicit. Reasoning is documented. Disagreement becomes visible.

The preamble still applies-but it requires new discipline in async contexts.

II. Async Principle 1: Write as If Explaining to the Team

In sync communication, you can hedge, soften, and gauge reaction live. In async, you must commit to the page.

Core preamble principle: Correctness Over Agreement

Async application: Your writing must invite scrutiny, not defensiveness.

How It Works

Bad (looks harsh in writing, invites defensiveness):

Your approach is flawed. We should use X instead.

Good (clear, invites discussion):

I'm concerned about this approach because [specific risk].
Have you considered X? Here's why I think it fits better: [reasoning].
Happy to discuss-maybe you've already thought through these concerns.

Better (even clearer):

Strong point about [their idea]. One concern I have: [specific issue].
Why? [reasoning with context].
I'm not certain this is the best path. Could be wrong-what am I missing?

The Discipline

Writing forces you to:

• Name the assumption - “I’m assuming…” makes your thinking transparent
• Show your reasoning - Not just “this is better,” but why
• Invite counter-argument - “Maybe I’m wrong about this” is not weakness, it’s clarity
• Separate observation from prescription - “Here’s what I see” vs. “Here’s what you should do”

Why this matters: Async readers can’t hear your tone. They can only read your words. If they feel dismissed, they won’t engage. If they see genuine thinking, they will.

III. Async Principle 2: Context Starvation Demands Explicitness

Async communication is fragmented: Slack threads, GitHub PRs, email chains, meeting notes. Each message stands alone. The full context isn’t present.

Core preamble principle: Truth Over Tone

Async application: Provide context in every message. Assume the reader doesn’t have the full picture.

How It Works

Bad (requires reader to have full context):

This is a problem. We talked about this last week.

Good (provides context in the moment):

Last week in standup we decided on approach X because [reason].
Looking at the implementation, I see [specific issue] that we didn't anticipate.
This means [impact]. I think we should revisit our decision because [reasoning].

The Discipline

• Quote relevant context - If referencing a decision, quote it or link to it
• Explain your frame - “From the security perspective, this matters because…”
• State assumptions you’re making - “Assuming we still want [goal]…” makes it easy to correct you
• Summarize the ask - What decision or input do you need?

Why this matters: Async readers can’t ask “what do you mean?” in real-time. If your message is unclear, they’ll either misunderstand or go silent. Explicitness prevents that.

IV. Async Principle 3: Timing Replaces Real-Time Negotiation

In synchronous communication, you debate until resolved. In async, timing becomes strategy.

Core preamble principle: Challenge early, decide clearly, execute aligned

Async application: Distinguish between discussion time and decision time.

How It Works

Decision Clock Pattern:

Starting discussion: [date/time]
Will decide by: [specific date/time]
Needed input: [what you need to decide]
Current options: [list with trade-offs]

What changes:

• People know there’s a deadline
• They can plan when to engage
• No assumption of continuous debate
• Clear when decision authority takes over

Example:

We need to decide on database approach. Here are the three options with trade-offs.
Discussion open until Friday EOD. I'll synthesize input and decide Monday morning.
If you have strong concerns, flag them with reasoning by Friday.

The Discipline

• Set decision clocks explicitly - Not vague (“soon”), but specific
• Announce who decides - “I’ll make the final call” is clearer than “we’ll see what the team thinks”
• Accept you might be wrong - Decision clock doesn’t mean you’re certain, means you’re committing to move
• Document the reasoning - Future you and the team will appreciate knowing why you decided

Why this matters: Async teams get stuck in perpetual debate because there’s no natural conversation endpoint. Decision clocks force closure while still inviting input.

V. Async Principle 4: Written Challenge Requires Courage, Not Softness

The biggest risk with async is that people go silent. They don’t challenge because it feels riskier in writing.

Core preamble principle: Critical, Not Servile

Async application: Be direct in writing. But direct ≠ harsh.

How It Works

Too soft (people miss the challenge):

Interesting approach! I wonder if maybe there could potentially be
some considerations around [vague concern]?

Direct AND respectful (people hear you):

I see value in this approach. I have a real concern: [specific issue].
Here's why it matters: [reasoning]. What am I missing?

Even better (invites counter-challenge):

I might be wrong here, but I see a risk: [specific].
I'm not certain we have the right answer. Your thoughts?

The Discipline

• Name the concern directly - “I’m worried about X” not “one might wonder about possibly X”
• Show you’ve thought it through - “Here’s why this specific issue matters…” not vague hand-waving
• Leave room for being wrong - “Tell me if I’m missing something” shows confidence, not insecurity
• Respect their expertise - “You know this better than me. But from my perspective…” honors different perspectives

Why this matters: In async, soft challenge reads as passive-aggressive (“are they actually concerned or just being polite?”). Direct challenge reads as engagement. People respect directness more than they appreciate artificial softness.

VI. Async Principle 5: Psychological Safety Requires Visibility

In sync teams, psychological safety builds through many small moments. You take a risk, it’s accepted, you take another. Repeat until trust exists.

In async, those moments are visible to everyone. But they’re also more fragile.

Core preamble principle: Think Holistically

Async application: Build trust through consistent patterns, not perfect moments.

How It Works

What kills async psychological safety:

• Silent disagreement (person goes quiet)
• Slow response to challenges (feels like dismissal)
• Decisions that revert challenges (inviting input but ignoring it)
• One harsh response in a thread (poisons the well)

What builds async psychological safety:

• Leader visibly changes mind based on input
• Quick acknowledgment of challenges (“good point, haven’t thought of that”)
• Transparent decision-making (showing why you chose what you chose)
• Consistent tone (professional, not defensive when challenged)
• Escalating up, not shutting down (when someone challenges, others feel safer too)

Examples

Building it (over many interactions):

[Day 1] Someone challenges an approach.
Response: "You're right, I hadn't thought about X. Let me reconsider."

[Day 2] Someone asks a tough question in Slack.
Response: "Good catch. That's a real constraint I should have mentioned."

[Week 1] Someone disagrees in a PR.
Response: "I see your point. Different approach has trade-offs, but yours is better for this. Changed."

Pattern emerges: Challenges are welcomed, considered, and sometimes change outcomes.
Result: Team feels safe disagreeing.

Destroying it (one bad pattern):

[Iteration 1] Person challenges. Leader: "Sounds good, thanks for input."
[Iteration 2] Same person challenges. Leader: "We already discussed this."
[Iteration 3] Same person goes silent. Different person challenges. Also goes silent.

Pattern emerges: Challenges are acknowledged but ignored.
Result: Team stops trying. Async becomes performative.

The Discipline

• Respond quickly to challenges - Even if your response is “good point, let me think about it”
• Be visibly responsive - If someone raises a concern, they should see you considered it
• Change your mind in public - When you do, explain why the challenge convinced you
• Address not dismiss - “We’re going forward with X because [reason]” not “We’re doing X, final decision”

Why this matters: Async safety is fragile because silence is the default. You must actively build it through consistent patterns.

VII. Async Anti-Patterns

Anti-Pattern 1: The Long Thread That Never Resolves

What it looks like:

• 47 messages debating one decision
• Half the team drops out
• No clear resolution
• Everyone confused about what was decided

Prevention:

• Thread gets long (>10 messages), move to structured format
• State decision at the top of thread, mark as resolved
• Don’t let threads become archives of thinking

Anti-Pattern 2: “Synchronous Async” (Waiting for Responses)

What it looks like:

• Person sends message, then waits
• Keeps checking for response every 5 minutes
• Frustrated when people don’t respond immediately

Prevention:

• Async means async. Send your input, move on to other work
• Don’t create urgency artificially
• If you need something urgent, use sync communication (call, chat)
• Respect that people are in different time zones

Anti-Pattern 3: Hidden Disagreement

What it looks like:

• Person disagrees but goes quiet
• Later, they undermine the decision in execution
• Or they bring it up in 1-on-1, not in public

Prevention:

• Make disagreement visible: “I think this is a risk, but I understand the decision”
• Document your concern: “I wanted this recorded because it might matter later”
• If you can’t live with the decision, escalate-don’t hide and sabotage

Anti-Pattern 4: Performative Inclusivity

What it looks like:

• “What do you all think?” then decision already made
• Asking for input on decided matters
• Theater of collaboration, not actual collaboration

Prevention:

• Only ask if you’re genuinely open to answers
• Mark things as decided vs. still open
• Explain constraints that limit options (“We need to decide by Friday because…”)

VIII. Async Skill Development

This doesn’t come naturally. Async communication requires discipline that sync doesn’t.

Skills to Build

Writing clarity:

• Make your thinking visible
• Explain assumptions explicitly
• Separate observation from opinion

Timing judgment:

• When to challenge vs. when to trust
• How long to discuss vs. when to decide
• When to escalate vs. when to accept

Reading between lines:

• Understanding intent when tone is missing
• Not assuming harsh tone when probably direct
• Recognizing silent disagreement

Decision-making:

• Making calls with incomplete input
• Documenting reasoning
• Being open to revisit if new info emerges

How Teams Improve

1. Model it - Leaders write clearly, decide with reasoning, change minds visibly
2. Normalize it - “That PR comment could be clearer, try [example]”
3. Debrief it - In retros: “That async discussion worked/didn’t work because…”
4. Iterate - Async communication improves with practice and feedback

IX. When to Use Sync Instead

Not everything should be async. Some decisions need sync communication:

Use sync when:

• Decision is complex with many variables
• Misunderstanding is high-risk
• Emotion or relationship is at stake
• Time is genuinely urgent
• Creative brainstorming needed
• Someone is clearly confused and async isn’t clarifying

Use async when:

• Everyone can read the same information
• Time isn’t urgent
• Reasoning needs to be documented
• People need time to think before responding
• Decision doesn’t need many perspectives at once

Best teams use both: Async for most work, sync for the decisions that matter most.

Summary: Async Doesn’t Change Preamble, It Extends It

Core preamble principles remain:

• Correctness Over Agreement - Write to invite scrutiny
• Critical, Not Servile - Be direct in writing
• Truth Over Tone - Provide context, not softness
• Think Holistically - Build safety through patterns

Async adds discipline:

• Explicitness - Say what you mean clearly in writing
• Timing - Decision clocks replace natural conversation endpoints
• Visibility - Your challenges and responses are all recorded
• Courage - Speaking up in writing feels riskier and requires more intent

Teams that master async apply preamble thinking harder, not differently.

Related Commands

• /pb-preamble - Core principles (Part 1)
• /pb-standup - Async communication for status
• /pb-pr - Code review as async challenge
• /pb-cycle - How peer review can be async
• /pb-team - Building psychological safety in remote teams

Async & Distributed Teams - Natural progression from core preamble thinking.

Preamble Part 3: Power Dynamics & Psychology

Extending core preamble thinking to hierarchies, authority, and the psychological reality of power differences.

Resource Hint: opus - Nuanced reasoning about power dynamics and psychological safety.

When to Use

• Addressing situations where juniors hesitate to challenge seniors
• Building structures that make honest feedback safe across levels
• Diagnosing why “think like peers” is not working in practice

I. The Reality: Power Isn’t Irrelevant

The core preamble says “think like peers, not hierarchies.” This is the goal. But the honest truth:

In most organizations, power is real:

• Your manager controls raises, promotions, assignments
• Senior people have more context and experience
• Hierarchy exists for reasons (speed, accountability)
• Not everyone has equal ability to speak up

The preamble-in-real-life challenge: Can a junior engineer actually challenge their senior architect? Can a new team member question the director’s decision?

The honest answer: Not without effort. But with the right structure, they can.

This part addresses that gap. How do we extend preamble thinking to organizations that have power differences, while honestly acknowledging those differences exist?

II. The Power Dynamic: What’s Really Happening

What Power Means in Practice

Power is:

• Ability to make decisions
• Control over resources (budget, assignments, time)
• Control over consequences (raises, promotions, feedback)
• Access to information others don’t have
• Authority to veto or overrule

Power isn’t:

• Having the best ideas
• Being right more often
• Being smarter or more skilled
• Deserving to have the final say

The mistake: Confusing authority with correctness.

Why This Matters for Preamble Thinking

Core preamble assumes the best idea wins regardless of who says it. But in hierarchies:

• A junior person’s great idea might not surface because they feel unsafe saying it
• A senior person’s mediocre idea might win because nobody dares challenge it
• Psychological safety is impossible if power is weaponized

The goal: Separate authority (yes, you decide) from correctness (no, that doesn’t mean you’re right).

III. Challenge Across Power: The Rules

Rule 1: Challenge the Decision, Not the Authority

This kills challenge:

Senior person: "We'll use microservices."
Junior person (thinking): "That's wrong. But I can't say that."

This enables challenge:

Senior person: "We'll use microservices because [reasoning about scale, team composition]."
Junior person: "I understand the reasoning. One concern: [specific risk based on experience].
Have you considered [alternative]?"

What changed: Moving from implicit (“who are you to disagree?”) to explicit reasoning that can be examined.

Rule 2: Challenge With Evidence, Not Feelings

Vague challenge (easy to dismiss):

"I just feel like this is risky."

Strong challenge (hard to dismiss):

"I'm concerned about this risk: [specific technical or organizational issue].
Here's why: [reasoning]. I've seen this pattern in [examples/experience].
What am I missing about why you think it's okay?"

Why this matters: Evidence-based challenge is harder to reject emotionally. It forces the decision-maker to think, not just assert authority.

Rule 3: Challenge Privately If It’s About Them, Publicly If It’s About the Idea

Bad (public character challenge):

In a meeting: "You always do this. You never listen. That's why this decision is bad."

Good (public idea challenge):

In a meeting: "I have concerns about this decision. Here's the technical risk: [specific].
Happy to discuss."

Good (private character feedback):

1-on-1: "I've noticed a pattern where you seem dismissive of junior input.
I want to be direct: it makes me hesitant to speak up. Is that intentional?"

Why this matters: Public criticism of ideas is fair game. Public criticism of character is delegitimizing. Save character feedback for private, one-on-one settings.

Rule 4: Challenge When It Matters, Not Everything

Destroying the privilege with overuse:

Challenge about architecture decisions: Good.
Challenge about their coffee choice: Why?
Challenge about their word choice in a sentence: Respect their autonomy.

Building credibility:

• Challenge 2-3 things per month, not 2-3 things per meeting
• Challenge when the stakes are real
• Let them win some discussions
• Show judgment about what’s worth challenging

Why this matters: If you challenge everything, nothing gets challenged (you become noise). If you challenge thoughtfully, your challenges carry weight.

IV. When Authority Should Matter Less

Some domains require less deference to authority. Some domains require more. The job is knowing which is which.

Authority Matters Less In:

Technical correctness

• A junior person can be right about a bug and senior person wrong
• Code either works or it doesn’t
• Example: “This function has off-by-one error. Here’s the fix.”

Customer impact

• A junior person closer to customers might see risks senior people missed
• Example: “I talked to users and they’re confused by this workflow. Have you gotten feedback?”

Operational reality

• A junior person might see constraints senior people don’t live with daily
• Example: “This deploy process you designed requires 4 hours. We’ve been shipping weekly.”

Risk identification

• A junior person might see security or scale risks
• Example: “This handles 10k requests. What if we hit 100k?”

Authority Matters More In:

Strategic context

• Senior people have information you don’t
• “We’re selling this line of business” is context that changes everything
• You can ask questions, but they might not be able to fully answer

Resource constraints

• Senior people manage budgets, timelines, organizational politics
• “Why not hire more people?” might have answers you don’t see
• You can question, but trust they’ve considered it

Accountability

• Senior people are responsible if it goes wrong
• Their authority is partly proportional to their responsibility
• You can input, but they own the decision

Organizational boundaries

• Some decisions aren’t your function to challenge
• Junior engineer challenging CEO’s strategic direction is different from challenging tech lead’s architecture
• Know the limits of your domain

V. Senior Person Responsibilities: Using Authority Well

If you have authority, you have special obligations.

Responsibility 1: Genuinely Invite Challenge

Theater (claiming to invite challenge while punishing it):

"I want to hear dissenting views. What do you think?"
[Person challenges]
"Well, I've already decided. Just wanted your input."
[Person learns: challenging is pointless]

Real (inviting and sometimes accepting challenge):

"I'm thinking about doing X because [reasoning]. I'm not certain.
What concerns do you have? I might change my mind."
[Person challenges with evidence]
"You know what, you're right about that risk. Let's do Y instead."
[Person learns: challenging sometimes works]

Responsibility 2: Explain Your Reasoning, Not Just Your Decision

Bad:

"We're using PostgreSQL. Final decision."

Good:

"We're using PostgreSQL because: [specific reasoning about our use case].
It's not perfect-tradeoffs are [list]. But for us, this is the right call.
Questions?"

Why this matters: When people understand your reasoning, they can challenge it meaningfully. When you just assert, they either agree or resist-no real thinking happens.

Responsibility 3: Demonstrate You Can Change Your Mind

This might be the most important one.

If you never change your mind based on input, you’re teaching people not to input. Even if you’re right 95% of the time, that 5% where you change builds trust for the 95%.

Examples of actually changing:

• “I said X, but your point about [specific concern] changed my thinking. Let’s do Y.”
• “I didn’t consider [that angle]. That’s a good catch. Let me reconsider.”
• “You’re right, I was wrong. Here’s why I was wrong, and what we’ll do differently.”

Why this matters: People believe you want challenge when they see it work. Not promises, not theater. Actual instances where challenge changed the outcome.

Responsibility 4: When You Overrule, Explain Why

Bad (just deciding):

"I've heard all perspectives. We're going with A."

Good (explaining the overrule):

"I've heard the concerns about A: [summarize the challenge].
I'm still choosing A because [reasoning that explains why the challenge didn't convince you].
I could be wrong. We'll revisit in [timeframe] and see if the risks materialized."

Why this matters: Even when you decide not to be swayed, explaining why maintains the person’s dignity and shows you actually considered them.

VI. Challenge Across Hierarchy: For the Junior Person

How to Challenge Upward Safely

Setup (before you challenge):

• Build credibility first. Do good work, ask thoughtful questions
• Choose your battles. Challenge things that matter
• Get evidence. Don’t challenge on vibes
• Understand their perspective first. “I understand you’re deciding X because [reasoning], right?”

The challenge itself:

"I understand the reasoning. I have a concern I want to surface: [specific].
Here's why I think it matters: [reasoning].
What am I missing about this?"

Key elements:

• Show you understand their perspective
• Name the concern directly (not hint)
• Provide reasoning (not just feelings)
• Ask what you’re missing (leaves them authority)

After the challenge:

• If they change their mind: “Thank you for listening. This is better.”
• If they don’t: “I understand. Let’s execute this and see what happens. I’ll keep watching for my concern to materialize.”
• If it does materialize: “Remember I flagged this? Happening now. What do we do?”

Why this matters: You’re building a track record. “I flag important things and I’m often right” is credibility. Over time, that means your challenges get heard.

What If They Punish You for Challenging?

This is a serious signal. If challenging has negative consequences (tone shift, unfair treatment, exclusion), you have a problem that’s bigger than preamble.

What to do:

1. Document it - Keep records of what you challenged and how they responded
2. Test it again - Is it consistent? Is it really punishment or projection?
3. Talk to them 1-on-1 - “I noticed you seemed frustrated when I raised [concern]. Did I handle that poorly?”
4. Escalate if it continues - Talk to HR, their manager, or someone you trust
5. Consider leaving - If authority is actually being weaponized, the organization has a bigger problem

The hard truth: Some organizations aren’t ready for preamble thinking. You can’t change that alone. Protect yourself.

VII. Building Toward Preamble: Teams Without Psychological Safety

Not all teams start with safety. Some start with hierarchy, fear, and silence. How do you build toward preamble thinking on those teams?

Stage 1: Safe Small Challenges (Months 1-3)

What to challenge: Low-stakes, technical questions where you’re clearly right

"Is this the latest version of the library? I see a security patch."

What not to challenge: Strategic decisions, resource allocation, their competence

Goal: Demonstrate that challenging is possible and doesn’t hurt

How leaders help: Respond positively to safe challenges. “Good catch! Thank you for paying attention.”

Stage 2: Build One Trusted Relationship (Months 2-6)

You don’t need the whole team to feel safe. Build one relationship where challenge works.

With your manager: Small challenges with evidence With a peer: Vulnerability, showing you don’t have all the answers With a senior person: Specific technical questions that respect their expertise

Goal: One person experiences safe challenge. They model it for others.

Stage 3: Make Safety Visible (Months 3-12)

Once someone changes their mind based on your input, the risk calculus changes. Others see that challenge has real power.

What leaders do:

• When someone challenges and you change your mind, do it visibly: “I changed my mind because [person] pointed out [concern]. Better decision.”
• Thank people for challenges in meetings: “I appreciate you flagging that.”
• Follow up: If someone raised a concern and it turned out to matter, circle back: “Remember you were worried about X? It did become a problem. Your thinking was right.”

Goal: Challenge becomes normalized. Safety increases.

Stage 4: Systemic Safety (After 12+ months)

Once challenge is normal in meetings, retrospectives, planning, and decisions, you have safety at scale.

What this looks like:

• People disagree in meetings and nobody panics
• Leaders change their minds based on input
• Problems surface early instead of in production
• Junior people have input that senior people listen to

Important: This takes time. Don’t expect it in weeks. Culture change is months to years.

VIII. Special Cases: Sensitive Power Dynamics

Some situations are especially fraught. Here’s how preamble thinking applies:

Performance Reviews

Can you challenge your performance review? Yes. But with care.

Manager: "I think your execution could be faster."
You (bad): "That's not fair. You don't understand my work."
You (good): "I appreciate the feedback. Can you give me specific examples?
I want to understand what you're seeing so I can improve."
[Later, after thinking]
You (better): "I thought about your feedback. One thing I might do differently: [specific].
But I'm also concerned about [trade-off]. Can we talk about how to improve without sacrificing quality?"

Key: You’re not dismissing their authority. You’re asking clarifying questions and offering your perspective.

Compensation / Promotion

Can you challenge salary or promotion decisions? Yes. Carefully.

Manager: "We're not promoting you yet."
You (bad): "This is unfair. Everyone else..."
You (good): "I understand. Can you help me understand what I need to demonstrate
to earn a promotion? What are the gaps you see?"
[After working on those gaps]
You (better): "I've worked on [specific improvements]. I think I've closed the gaps you identified.
I'd like to revisit the promotion conversation."

Key: You’re not arguing about fairness. You’re asking for clarity and demonstrating progress.

Team Composition / Role Changes

Can you challenge being moved to a different team? Cautiously.

Manager: "We need you on the new platform team."
You (bad): "I don't want to. This is wrong."
You (good): "I want to understand the reasoning. Why this team, why now?
What happens to the project I'm on?"
You (better): "I understand the business need. I'm concerned about [specific impact].
Can we discuss options that meet the business need and address my concern?
[Specific alternatives]"

Key: You’re not refusing. You’re raising concerns and offering solutions.

Personality Conflicts

Can you challenge someone’s behavior toward you? Yes. Very carefully.

Not in a meeting with their boss: "You did X and it made me feel Y."
In a private 1-on-1: "I've noticed you interrupt me in meetings. Is that intentional?
It makes me hesitant to speak up."

Never: Publicly accuse someone of bias or poor behavior. Always: Handle it privately first.

IX. Dissent Escalation: A Clear Framework

When you disagree with a decision, what’s your path forward?

Level 1: Input During Decision (Primary)

Decision being made.
You: "I have concerns: [specific]. Here's why: [reasoning]."
Decision maker: Listens, considers, decides.
You: Execute and support, even if you disagree.

This is the normal path. Input is heard. Decision is made. You move forward.

Level 2: Request Reconsideration (Rarely)

Decision was made.
You: "I've been thinking about [specific risk you flagged].
It's becoming real. Can we reconsider?"
Decision maker: Considers new evidence. Might revert, might stick.
You: Accept and move forward.

This is when your concern becomes reality. The decision-maker reassesses.

Level 3: Escalation (Very Rarely)

Decision violates safety, ethics, or legality.
You: You speak to their manager or HR.

Examples: Safety risk being ignored, discrimination, fraud, destruction of value.

This should be rare. If you’re escalating frequently, either:

• You don’t trust the decision-maker (deeper problem)
• You don’t understand the constraints they’re operating under
• The organization has deeper dysfunction

Level 4: Non-Compliance (Extremely Rare, Career-Affecting)

Decision violates your core values.
You: You refuse to execute.

This is the nuclear option. You’re saying “I can’t do this.” This usually leads to:

• Being overruled and you leave the company, or
• Your concern being serious enough that organization changes

Only do this if you’re willing to leave.

X. Authority Earned Through Reasoning

The deeper principle: Authority should be earned through demonstrated good thinking, not just position.

How Authority Grows

Early in career: “What does the senior person think?” → They have more experience Mid career: “What does the senior person think, and do they have good reasoning?” → You start weighing answers Late career: You earn authority by consistently being right and changing your mind when you’re wrong

How Authority Shrinks

• Asserting decisions without reasoning
• Punishing people who challenge you
• Never changing your mind
• Making decisions that turn out badly and not learning
• Dismissing input from people with relevant expertise

The Goal

Authority based on reasoning is stronger than authority based on position.

When people follow your decisions because your reasoning is sound, not because you’re the boss:

• They’re more engaged
• They execute better
• They’re more likely to catch your mistakes
• The organization is healthier

Summary: Preamble Works Across Power, With Discipline

Core preamble principles remain:

• Challenge assumptions
• Correctness over agreement
• Truth over tone
• Think holistically

With power dynamics, you add:

• Clarity: Be explicit about reasoning, not just decisions
• Evidence: Challenge based on evidence, not feelings
• Discretion: Know what’s yours to challenge vs. trust
• Responsibility: Senior people must genuinely invite challenge and sometimes accept it
• Escalation: Clear paths for when normal challenge isn’t enough

The test: Does the best idea win, or does the senior person’s idea win?

If it’s the former, you have preamble thinking working across hierarchy. If it’s the latter, you have hierarchy working despite preamble thinking.

Related Commands

• /pb-preamble - Core principles (Part 1)
• /pb-preamble-async - How these apply in async (Part 2)
• /pb-team - Building team culture and psychological safety
• /pb-incident - Honest assessment under stress
• /pb-onboarding - Bringing people into preamble culture

Power Dynamics & Psychology - Real-world application of preamble thinking.

Preamble Part 4: Decision Making & Dissent

Extending core preamble thinking to decision finality, execution alignment, and organizational learning.

Resource Hint: opus - Decision frameworks require careful reasoning about trade-offs and organizational dynamics.

When to Use

• Teams stuck in endless debate without reaching decisions
• Establishing decision clocks and commitment protocols
• Balancing challenge culture with the need to ship

I. The Tension: Challenge vs. Movement

Core preamble invites challenge. Every decision gets examined. Assumptions get questioned. Trade-offs get surfaced.

But there’s a cost:

If you can challenge forever, nothing ships. Teams get exhausted. Debate becomes the mode instead of decision.

The tension is real:

• You want honest input
• But you also need to decide and move forward
• You want learning from past decisions
• But not endless re-litigation of past choices
• You want psychological safety
• But not paralysis

This part addresses how to honor both: genuine challenge + decisive action.

II. Decision Clocks: Creating Closure

The core principle: Challenge early, decide clearly, execute aligned.

The mechanism: Decision clocks.

How Decision Clocks Work

Before significant decisions, announce:

1. When the decision needs to be made (specific date/time)
2. How much input you want (what information matters)
3. Who decides (you, team consensus, some other process)
4. What happens after (decision is final, revisitable in [timeframe], etc.)

Example 1: Architecture Decision

DECISION CLOCK: Database Choice

Timeline:
- Now to Friday EOD: Discussion open
- Monday 9am: Final decision announced

Input wanted:
- Technical constraints we haven't considered
- Experience with each option
- Deployment/operational impact
- Scaling concerns for our projected growth

Decision maker: I'm deciding this based on:
- Your input + my analysis
- Trade-offs documented (I'll share my reasoning)

After decision:
- We commit to this for 18 months minimum
- Revisit only if fundamental constraints change
- We'll document why we chose this for future reference

Example 2: Process Change

DECISION CLOCK: Code Review Process

Timeline:
- Feedback window: This week (I want your perspective)
- Decision: Friday morning
- Implementation: Next Monday

What I'm optimizing for:
- Catching real bugs
- Shipping faster
- Reducing meeting load

What would change my mind:
- Evidence this will hurt quality
- Operational concerns from teams doing the reviews
- Better alternative that addresses all three

After decision:
- We'll try it for 4 weeks
- We'll measure: bugs caught, shipping speed, meeting time
- We'll revisit based on results

The Discipline

Before launching a decision clock:

• Be genuine about openness (are you actually willing to change your mind?)
• Be clear about constraints (what can’t change, and why?)
• Be specific about timing (not “soon,” but actual date/time)
• Be explicit about process (how will you decide? it’s not just “I’ll think about it”)

During the discussion window:

• Listen. Don’t defend your initial idea
• Ask clarifying questions
• Push back on vague input (“give me specifics”)
• Take notes on concerns

When announcing the decision:

• Explain your reasoning
• Acknowledge concerns (even ones you’re not addressing)
• Explain why you chose what you chose
• Be clear about what’s not revisitable in the near term

Why This Works

Decision clocks solve the impossible choice between challenge and movement:

• People know they have time to raise concerns (removes urgency pressure)
• People know when debate stops (removes perpetual debate)
• People know you’ve considered their input (even if you didn’t change your mind)
• Decisions get made and teams move forward

Without decision clocks: Teams get stuck arguing forever, or leaders shut down discussion to force closure (kills safety).

With decision clocks: Challenge happens, then movement happens, then learning happens.

III. Loyalty After Disagreement: Execution Alignment

You challenged the decision. Your concerns weren’t addressed. Decision was made anyway. Now what?

The Three Levels

Level 1: Alignment

You: "I still have concerns about this. But I understand the decision.
Let's execute and see what happens. I'm all in."
[You execute well. You watch for your concerns to materialize.]

This is the normal path. You disagree, decision is made, you execute professionally.

Level 2: Documented Dissent

You: "I want to document that I had concerns about [specific risk].
Not to undermine the decision, but for the record.
If this comes up later, I want it noted that I flagged it."
[Decision maker documents your concern.]
[You execute the decision while maintaining documentation.]

This is for serious concerns. You’re saying “I think this might fail, but I’ll execute anyway.”

Level 3: Can’t Execute

You: "I can't execute this. It conflicts with [reason: ethics, safety, values].
I need to escalate."

This is rare. You’re saying the decision is fundamentally wrong and you won’t participate.

Level 4: Leaving

You: "This decision represents a fundamental mismatch between my values and the organization.
I'm leaving."

This is extremely rare. The decision has made you realize you don’t belong here.

The Key Distinction

Loyalty ≠ Agreement

Loyalty means:

• You execute the decision well, even though you disagree
• You help the team succeed
• You don’t undermine the decision
• You gather data on whether your concerns were valid
• You do this professionally

Loyalty does NOT mean:

• Pretending you agree
• Suppressing your actual concerns
• Sabotaging from within
• Hoping it fails so you can say “I told you so”

What Leaders Should Expect

After a decision:

• Some people will disagree and execute anyway (healthy)
• Some people will have concerns they want documented (healthy)
• Some people will check out mentally (problem to address)
• Some people will sabotage (red flag)

Your job as leader: Monitor for the last two. Have 1-on-1s with people who seem disconnected.

You: "I noticed you seemed quiet during the decision.
How are you feeling about moving forward?"
Them: "Honest? I think it's a mistake."
You: "I get it. I'm concerned too. Here's why I'm still going forward anyway.
What would you need to feel okay executing this?"

IV. When to Revisit vs. When to Stick

Not all decisions are equal. Some should be revisited quickly. Some should stick for years.

Revisit Quickly When:

New information changes the equation:

Decided: "We're launching in Q2"
New info: Key team member leaving, supply chain disruption
Response: Revisit immediately

Assumptions were wrong in ways we can now verify:

Decided: "Use tech X because it's cheaper"
Reality: Tech X is actually more expensive to operate
Response: Revisit after 2-4 weeks

The decision was explicitly time-gated:

Decided: "Try approach A for 4 weeks, then revisit"
After 4 weeks: Revisit as planned
Response: Follow through on the gate

Stick When:

You’re in the implementation window:

Decided: Use PostgreSQL
2 days into implementation: "Actually, should we use MongoDB?"
Response: Not now. Finish the implementation cycle, then revisit.
Exception: Only if implementation reveals fundamental flaw (impossible to use, security risk)

The decision is costly to reverse:

Decided: Migrate to cloud platform
1 month in: "Hmm, maybe we should stay on-prem?"
Response: Stick for minimum 6 months. Revisit with clear criteria.
Exception: Only if costs are wildly different or outcomes are worse than projected

You just made the decision:

Decision was made 2 days ago. Someone wants to revisit.
Response: No. Decision windows close. Move forward.
Exception: New critical information (safety, legal, major business change)

People are using disagreement as power play:

Decision made on architecture. Senior person X didn't get their way.
X keeps suggesting alternatives in meetings.
Response: "The decision is made. We're moving forward. Revisit in [timeframe]."

Decision Reopening Criteria

If someone wants to reopen a decision, use these criteria:

1. How much new information?

   • Trivial → No
   • Clarifying → Maybe
   • Game-changing → Yes

2. How far in are we?

   • No work done → Can revisit
   • 25% through → Expensive but possible
   • 75% through → Stick unless critical
   • Done → Only if major failure

3. Who’s asking?

   • Person who didn’t like it first time → No (unless new info)
   • Person with new information → Yes
   • Team → Depends on criteria 1 & 2

4. What’s the cost of revisiting?

   • Revisiting costs more than sticking → Stick unless critical
   • Revisiting costs less → Might be worth it

Use all four criteria together. Not just one.

V. Decision Documentation: Why We Decided

One of the most useful practices: documenting why you decided, not just what you decided.

What to Document

Decision: What we’re doing Context: Business situation at the time Alternatives: What else we considered Rationale: Why we chose this Assumptions: What we’re assuming is true Revisit date: When we’ll check if this is still right

Example

DECISION: Use PostgreSQL for new service

Context:
- Growing user base (10k → 50k projected)
- Real-time reporting needed
- Team has PostgreSQL expertise
- Migration from legacy system

Alternatives considered:
1. MongoDB - flexible schema, easier scale-out
   Rejected because: No team expertise, real-time queries harder
2. Stay on legacy Oracle - maintains compatibility
   Rejected because: We're migrating away, doesn't help new features
3. DynamoDB - AWS-native, good scale
   Rejected because: costs would be higher at our scale, ACID important

Rationale:
- Mature, battle-tested
- Team knows it well
- ACID transactions important for reporting accuracy
- Good for our projected scale

Assumptions:
- We'll hit 50k users (if not, this is overkill, but doesn't hurt)
- Real-time reporting stays critical (might change if product strategy shifts)
- PostgreSQL keeps pace with growth (might need sharding in 5+ years)

Revisit: If we exceed 500k users or if reporting strategy changes

Why This Matters

For future decisions:

• You can see what you assumed
• You can see what alternatives you rejected and why
• You can understand trade-offs

For learning:

• Did your assumptions hold? Great data point.
• Did they not? Learn what you missed.
• Can improve future decision-making

For challenges:

• “I disagree with this decision” is much easier to evaluate if you understand the reasoning
• “I disagree with this alternative you rejected” can be reconsidered if circumstances changed

VI. Decision Learning: Post-Mortems Without Blame

Decisions fail sometimes. The goal: learn without creating blame culture.

What Kills Learning

Blame focus:

"This decision was stupid. Jane should have known better."
Result: Jane gets defensive. Others stay quiet. No one learns.

Perfection expectation:

"We should have seen that coming. Why didn't we predict it?"
Result: People become paralyzed. Next decisions take forever.

Decision reversal:

"That was the wrong call. We never should have done it."
Result: Trust in decision-making erodes. People second-guess everything.

What Enables Learning

Assumption focus:

"We assumed X was true. It turned out to be false. What does that tell us?"
Result: Understanding of how we think. Improvements to future decisions.

Context humility:

"With the information we had at the time, this was a reasonable decision.
New information changed the outcome. Here's what we learned."
Result: People understand good decisions can have bad outcomes.

Process improvement:

"The decision-making process served us well. The assumption-checking could be better.
Here's how we'll improve."
Result: Future decisions are stronger.

Running a Good Post-Mortem on Decisions

Step 1: Acknowledge the outcome

"We decided X. Outcome was Y (worse than hoped).
This is a post-mortem, not a judgment."

Step 2: Review the assumptions

"At the time, we assumed: A, B, C
Which of those turned out to be wrong?"

Step 3: Understand why the assumption was wrong

"We thought B would be true because [reasoning].
It wasn't because [what changed or what we missed]."

Step 4: What would have changed the decision?

"If we had known X was false, would we have decided differently?"
If yes: We made a good decision with bad luck.
If no: Our decision was flawed beyond assumptions.

Step 5: What do we learn?

"For next time, we should:
- Question this assumption more explicitly
- Gather data on this earlier
- Plan for this outcome
- Have a reversal mechanism
"

Step 6: Document it

Add to decision documentation:
"Outcome: [result]
What we learned: [key learnings]
"

The Shift

From: “Bad decision = someone failed” To: “Bad outcome = what did we learn?”

This subtle shift changes everything. People become willing to make bold decisions because failure is learning, not judgment.

VII. Challenge Fatigue: Knowing When to Stop

There’s a cost to perpetual challenge. Teams get exhausted. Debates drag on. Decisions never get made.

Signs of Challenge Fatigue

In individuals:

• Stops speaking up (challenge feels pointless)
• Complains in hallways instead of meetings (lost faith in process)
• Less energy, more cynicism
• Starts looking for new jobs

In teams:

• Meetings get longer, not shorter
• Same arguments come up repeatedly
• New people ask “are we always like this?”
• Nothing gets decided without hours of debate

In organizations:

• Execution slows down
• Competitors ship faster
• People feel depleted

Preventing Challenge Fatigue

Use decision clocks (Section II) - Removes perpetual debate

Distinguish between:

• Strategic challenges (worth debating more)
• Tactical challenges (make decision and move)

Set challenge budgets:

"We can spend 4 hours on this decision.
Not more. Let's use the time well."

Track decision velocity:

"How many decisions are we making per week?"
[If down] "We're being too careful."
[If up] "We might be skipping important thinking."

Leader responsibility:

If you see fatigue, name it.
"I'm noticing people seem frustrated. We might be over-debating.
Let's tighten decision clocks next week."

The Balance

Too little challenge: Mediocre decisions, people feel unheard

Right amount of challenge: Good decisions, people feel heard, movement happens

Too much challenge: No decisions, people burned out, nothing ships

Finding the balance: Experiment. If you’re shipping slowly, tighten clocks. If quality is dropping, loosen them.

VIII. Cost-Benefit of Challenge

Not every decision deserves hours of debate.

High-Stakes Decisions (Debate More)

Characteristics:

• Hard to reverse
• Affects many people
• Long-term impact
• High financial impact
• Security/safety implications

Examples:

• Architecture decisions
• Technology migrations
• Hiring decisions
• Firing decisions
• Major product changes

How much debate: Hours to days. Worth the time.

Medium-Stakes Decisions (Moderate Debate)

Characteristics:

• Can be reversed
• Affects some people
• Medium-term impact
• Moderate cost to reverse

Examples:

• Process changes
• Tooling choices
• Meeting structures
• Documentation requirements

How much debate: Minutes to hours. Not days.

Low-Stakes Decisions (Minimal Debate)

Characteristics:

• Easily reversible
• Affects few people
• Temporary
• Minimal cost to reverse

Examples:

• Meeting time
• Communication channel
• Formatting standards
• Temporary workarounds

How much debate: Minutes. Decide and move.

The Judgment Call

Junior people often: Challenge everything equally (no discrimination)

Senior people often: Skip challenge on things that need it (overconfident)

Goal: Spend debate time where it matters most.

IX. Building Learning Organizations

The ultimate goal: an organization that gets smarter over time because it learns from decisions.

What Makes Organizations Learn

1. Decision documentation

• Why did we decide this?
• What were we assuming?
• What happened?
• What did we learn?

2. Regular review

• Not “we were wrong” but “our assumptions didn’t hold”
• Not blame but “what can we improve?”

3. Acting on learning

"Last time we assumed X and we were wrong.
This time, let's test it earlier."

4. Sharing across teams

"Team A learned that our prediction about scale was off.
Team B, this affects your planning."

5. Feedback loops

• Decision made → Assumptions documented
• Execution happens → Assumptions tested
• Outcome measured → Learning captured
• Future decisions improved

Scaling Learning

Small teams (5-10): Informal. Share in retros.

Medium teams (10-50): ADRs, decision documentation. Share in all-hands.

Large organizations (50+): Formal decision registry. Learning from one team shared across org.

Summary: Decision Discipline

Core preamble principles remain:

• Challenge assumptions
• Correctness over agreement
• Truth over tone
• Think holistically

Decision discipline adds:

• Decision clocks - Challenge has a window, then closure
• Execution alignment - After decision, you execute well even if you disagree
• Revisit criteria - Clear rules for when to reopen vs. stick
• Documentation - Why we decided, not just what
• Learning culture - Outcomes teach us without blame
• Challenge budgets - Debate time is finite, use it wisely

The result:

• Genuine challenge happens
• Decisions still get made
• Teams stay energized
• Organizations learn
• Execution is strong

Related Commands

• /pb-preamble - Core principles (Part 1)
• /pb-preamble-async - How these apply async (Part 2)
• /pb-preamble-power - Power dynamics (Part 3)
• /pb-adr - Architecture Decision Records (decision documentation)
• /pb-incident - Learning from failures

Decision Making & Dissent - Completing the philosophy foundation.

Design Rules: Core Technical Principles

The preamble tells us HOW teams think together. Design rules tell us WHAT we build. Together, they form the complete framework for engineering excellence.

Resource Hint: sonnet - Reference material for applying established design principles.

When to Use

• Making architectural or design trade-off decisions
• Reviewing code or designs against core principles
• Settling disagreements about “the right way” to build something
• Onboarding engineers to the team’s technical philosophy

Anchor: Why These 17 Rules Matter

These are 17 classical software design principles that have proven themselves across decades of software engineering. They’re not new. They’re not trendy. But they’re foundational because they describe how to build systems that work, last, and adapt.

The critical insight: When a team uses preamble thinking (challenge assumptions, prefer correctness over agreement, think like peers), they need design rules to guide WHAT they’re building. Without design rules, good collaboration produces poorly-designed systems. Without preamble thinking, teams debate design rules endlessly without resolution.

How they apply to everything:

• Planning - Design decisions embody these rules from the start
• Development - Every architectural choice reflects these principles
• Review - Reviewers challenge based on which rules are violated
• Operations - Systems designed by these rules stay maintainable and adaptable

The four clusters below group the first 17 rules into memorable themes: CLARITY, SIMPLICITY, RESILIENCE, and EXTENSIBILITY. A fifth theme, ATTENTION, captures Rule 18 (Attention as a Finite Resource). Together, these 18 rules provide a complete framework for technical decision-making.

Cluster 1: CLARITY - Design for Understandability

1. Rule of Clarity: Clarity is Better Than Cleverness

The Principle: When you have a choice between a clever solution and a clear solution, choose clarity every time. Clever solutions impress the author; clear solutions serve everyone who reads the code.

Why It Matters: Code is read far more often than it’s written. A clever solution that only the author understands becomes a liability: it’s hard to debug, hard to modify, hard to teach. A clear solution is learned once and used forever.

In Practice:

• Explicit variable names beat cryptic abbreviations
• Simple control flow beats nested ternaries
• Obvious patterns beat surprising optimizations
• Readable code beats compressed code

When It Costs: Clarity sometimes means writing more code. Sometimes it means passing more parameters. That’s a trade-off you accept because clarity enables all future work on this code.

Philosophy: Sam Rivera’s Perspective

See /pb-sam-documentation for the complete clarity philosophy applied to documentation and knowledge transfer.

Core insight: Clarity is an act of respect for future readers. When you write code that’s easy to understand, you’re saying “I believe your time is valuable, so I wrote this for you, not for myself.”

• For yourself: You read code once and write it once.
• For everyone else: They read it dozens of times without your context.
• The math: 1 author, 10 readers over 3 years = clarity pays dividends.

2. Rule of Least Surprise: Always Do the Least Surprising Thing

The Principle: In interface design and API design, always choose the behavior users would expect. Don’t surprise them, even in clever ways.

Why It Matters: Surprise is context-switching. When an API behaves unexpectedly, developers stop working and debug. “Oh, that function modifies the original list” or “Oh, that parameter counts from zero” takes mental energy. Expected behavior is automatic; unexpected behavior is cognitive load.

In Practice:

• Convention over configuration (use industry standards)
• Consistent patterns across your codebase
• Clear error messages that explain what went wrong
• Predictable state transitions

Example: Don’t write a map() function that deletes elements. Write a filter() function instead. Users expect map() to transform without removing.

3. Rule of Silence: When There’s Nothing to Say, Say Nothing

The Principle: Programs should be quiet unless they have something important to communicate. Excessive logging, warnings, and output become noise that masks actual problems.

Why It Matters: When everything outputs constantly, important signals disappear. Someone runs the program, gets 50 lines of output, and can’t tell which lines matter. Real problems get missed because they’re drowned out by chatter.

In Practice:

• Verbose logging during development, silent in production
• Errors are loud; normal operation is quiet
• No progress messages for fast operations
• No warnings for expected edge cases

Example: A deployment that succeeds produces zero output. A deployment that fails produces a clear error. Not the reverse.

4. Rule of Representation: Fold Knowledge Into Data

The Principle: Make the data structure so clear that the logic becomes simple. The work of your program should be visible in the data, not hidden in the code.

Why It Matters: Logic is hard to reason about. Data structures are easy to reason about. When you push knowledge into data, the program becomes obviously correct instead of mysteriously working.

In Practice:

• Data structures that represent the problem domain
• Enums instead of magic numbers
• Explicit state in data structures, not implicit in control flow
• Type systems that enforce constraints

Example: Don’t represent “user role” as strings that you check with if role == "admin". Represent it as an enum:

enum Role { Admin, User, Guest }

Now the code is obviously correct: you can’t forget a case.

Cluster 2: SIMPLICITY - Design for Discipline

5. Rule of Simplicity: Design for Simplicity; Add Complexity Only Where You Must

The Principle: Simpler is better. Every line of code adds cost: reading, debugging, testing, maintaining. Before adding complexity, justify it.

Why It Matters: Complex systems fail in ways you didn’t anticipate. Simple systems fail in ways you can predict. A simple system with a known limitation is more reliable than a complex system that tries to handle everything.

In Practice:

• Start with the simplest solution that works
• Add features when you need them, not when you might
• Delete code that isn’t used
• Refuse “nice to have” complexity

When It’s Hard: Simplicity requires discipline. It’s harder in the moment: “Let me add support for X even though we don’t need it yet.” But you’re paying a cost every single day the code exists. That one “nice to have” feature might never be needed and costs you 1000 days of maintenance.

Philosophy: Simplicity as Product Discipline

See /pb-maya-product for the product lens on simplicity.

Core insight: Simplicity and scope discipline are inseparable. Every feature is an expense, paid daily in maintenance cost, complexity tax, and cognitive load. The simplest design isn’t about minimalist aesthetics-it’s about ruthlessly eliminating what you don’t need now.

• Shipping simple is faster - You know when code is done because it does exactly one thing well
• Debugging simple is faster - Fewer moving parts, fewer places where bugs hide
• Learning simple is faster - New developers read and understand in minutes, not hours
• Changing simple is faster - When requirements shift, you change less code

Trade-off clarity: You can have simple+slow or complex+fast. Prefer simple+slow every time-you can optimize later. Complex+fast almost always becomes complex+slow when you try to maintain it.

6. Rule of Parsimony: Write Big Programs Only When Clearly Nothing Else Will Do

The Principle: Before writing a big, complex system, prove that nothing simpler will work. Most monoliths started as microservices in someone’s head but couldn’t be simplified.

Why It Matters: Big programs are exponentially harder to understand and maintain. Before you choose this path, prove it’s necessary. Most of the time, three focused small programs beat one big one.

In Practice:

• Can you build this as an add-on? Do that instead.
• Can you use a library? Use it instead of writing it.
• Can you simplify the requirements? Do that before building big.

The Anti-pattern: “We’ll build a flexible framework that handles all possible cases.” You won’t use 80% of it. Delete it.

7. Rule of Separation: Separate Policy From Mechanism; Separate Interfaces From Engines

The Principle: Don’t mix different levels of abstraction. Keep the “what should happen” separate from “how it happens.” Keep the interface separate from the implementation.

Why It Matters: When you mix abstraction levels, changes ripple everywhere. When you expose implementation details, clients depend on them. You lose the ability to change anything without breaking everything.

In Practice:

• Interfaces that describe contracts
• Implementations that fulfill contracts
• Don’t leak implementation details
• Don’t require callers to understand how it works

Example:

Good: public interface List<T> { void add(T item); }
Bad:  public interface List<T> { void add(T item); void resize(); }

The bad version exposes that lists resize internally. Now clients can’t be changed without breaking code.

8. Rule of Composition: Design Programs to Be Connected to Other Programs

The Principle: Build things that work well together. Design systems as components, not monoliths. Make your output useful as someone else’s input.

Why It Matters: The moment you design for composition, you get reusability, modularity, and flexibility for free. Monolithic design requires you to do everything yourself.

In Practice:

• Clean interfaces between components
• Use standard data formats
• Unix philosophy: do one thing well
• Components that are useful independently

Example: A linting tool that writes JSON output can be used with any downstream tool. A tool that writes HTML can’t be piped to anything else.

Cluster 3: RESILIENCE - Design for Reliability and Evolution

9. Rule of Robustness: Robustness Is the Child of Transparency and Simplicity

The Principle: You build robust systems not by adding error handling everywhere, but by making systems so transparent and simple that errors are obvious and handling is straightforward.

Why It Matters: Complex error handling hides bugs. Transparent systems reveal bugs immediately. Simple systems fail predictably. The path to robust systems is NOT “more error handling,” it’s “less hidden complexity.”

In Practice:

• Fail fast and loudly
• Make state changes explicit
• Simple error handling (not nested try-catch blocks)
• Transparency enables quick recovery

Example: Bad: Complex error handling that tries to recover from any failure Good: Fail immediately when invariants are violated, so you know exactly what went wrong

Philosophy: Transparency as Defense

See /pb-alex-infra for resilience thinking and /pb-jordan-testing for failure mode discovery.

Core insight: Robust systems don’t hide problems; they broadcast them. Every layer of abstraction that conceals state increases the time between failure and discovery. Long detection latency means cascading failures.

• Fail at the boundary - Catch invalid input early, before it corrupts state
• Assert invariants - If data should never reach this state, assert it and crash
• Transparent state - Make it obvious what the system is doing (logs, metrics, traces)
• Test for failure - Don’t test “it works”; test “it fails correctly”

The paradox: Systems that fail loud and fast feel fragile. Systems that hide errors feel stable-until they corrupt your data.

10. Rule of Repair: When You Must Fail, Fail Noisily and As Soon As Possible

The Principle: Errors that hide are worse than errors that scream. When something goes wrong, make it obvious immediately, not hours later when data is corrupted.

Why It Matters: Silent failures compound. By the time you discover a problem, you’ve processed gigabytes of corrupted data. Loud failures let you fix the problem at the source, while the scope is still manageable.

In Practice:

• Assertions and checks
• Fail-fast validation
• Explicit error handling
• Clear error messages

Example: Don’t silently return null. Throw an exception. The exception tells you where the real problem is; null hides the problem until it causes cascading failures.

Philosophy: Fail at the Source

See /pb-linus-agent for pragmatic security thinking that applies here: catch problems early, before they propagate.

Core insight: Silent failures are worse than crashes. When code swallows an error, you delay diagnosis. The longer an error hides, the further it propagates. By the time you discover it, you’ve lost data, accumulated corruption, or exposed a security issue.

Loud failures cost you hours of debugging. Silent failures cost you days of data recovery and customer trust.

• Error at the edge - Validate input; reject early
• Crash on invariant violation - If state is impossible, stop immediately
• Clear error context - Stack traces, logs, and metadata that enable diagnosis
• No recovery guessing - If you can’t recover safely, don’t pretend to

The measure: “Time from failure to diagnosis.” Loud systems are fast; silent systems bury the information you need.

Recovery-oriented errors: Error messages should tell the consumer what to do next, not just what went wrong. This applies to human developers AND AI agents consuming your APIs, CLIs, or tools.

• Diagnostic only: “Element not found” - consumer is stuck
• Recovery-oriented: “Element not found. Available elements: [list]. Run snapshot to refresh.” - consumer knows next step

As AI-assisted development grows, your error messages are read by both humans and AI agents. Recovery-oriented errors reduce time-to-resolution for both. Design errors that guide the next action, not just report the failure.

11. Rule of Diversity: Distrust All Claims for “One True Way”

The Principle: Any claim that there’s ONE best way to do something is probably wrong. Most meaningful choices have trade-offs. Understand the trade-offs instead of following dogma.

Why It Matters: Dogma kills thinking. “We always use X” prevents you from choosing the right tool for the job. “Best practices are law” prevents you from adapting to your context.

In Practice:

• Understand why you’re choosing something
• Be prepared to choose differently for different contexts
• Challenge architectural dogma
• Use preamble thinking: question assumptions, don’t just follow rules

Example: Microservices aren’t always better than monoliths. Sometimes a monolith is the right choice. Understand the trade-offs for YOUR problem, then decide.

12. Rule of Optimization: Prototype Before Polishing. Get It Working Before You Optimize It

The Principle: Build it first. Make it work. Make it clear. THEN optimize, but only if you measure and find a real bottleneck.

Why It Matters: Optimization is expensive: added complexity, reduced readability, hard-to-predict failures. Most programs spend 80% of time in 20% of the code. Optimizing randomly costs you everywhere and helps nowhere.

In Practice:

• Measure before optimizing
• Profile to find the real bottleneck
• Optimize only the bottleneck
• Document why this code is optimized

The Anti-pattern: “This might be slow, so let me optimize it.” You’re adding complexity to solve a problem that doesn’t exist.

Philosophy: Clarity Before Speed

See /pb-sam-documentation for clarity thinking and /pb-alex-infra for measuring infrastructure performance.

Core insight: Premature optimization trades clarity for speed nobody measures. Before you optimize, you must:

1. Know what’s actually slow (measure, don’t guess)
2. Understand the code so well you can optimize it safely
3. Document why the optimization exists (so future maintainers don’t remove it thinking it’s dead code)

• Measure first - Profiling is cheaper than guessing
• Optimize after clarity - Code you understand is code you can safely optimize
• Document the optimization - Why is it this way? What’s the payoff vs cost?
• Accept performance debt - If you don’t know where the problem is, accept slower code rather than introduce complexity

The arithmetic: 1 hour measuring + 1 hour optimizing the right thing = 100x better ROI than 4 hours optimizing the wrong thing.

Cluster 4: EXTENSIBILITY - Design for Long-Term Growth

13. Rule of Modularity: Write Simple Parts Connected by Clean Interfaces

The Principle: Build systems as a collection of simple modules that communicate through clear, stable interfaces. This is the foundation of all other extensibility.

Why It Matters: Modular systems are:

• Easier to understand (one module at a time)
• Easier to test (test each module independently)
• Easier to change (change one module)
• Easier to reuse (use the module elsewhere)

In Practice:

• High cohesion within modules (similar things together)
• Low coupling between modules (minimal dependencies)
• Explicit interfaces (clear contracts)
• Clear boundaries

Example: A payment module doesn’t know about logging. Logging doesn’t know about payments. They communicate through agreed-on interfaces.

14. Rule of Economy: Programmer Time Is Expensive; Conserve It in Preference to Machine Time

The Principle: If you have to choose between using more CPU/memory/network and saving programmer time, choose to save programmer time. Machines are cheap; programmers are expensive.

Why It Matters: A slow program that you can understand and modify is more valuable than a fast program that’s impossible to understand. The opposite used to be true when computers were expensive and programmers were cheap. That world is gone.

In Practice:

• Use high-level languages and frameworks
• Let the computer do grunt work (generate code, optimize, etc.)
• Don’t optimize prematurely
• Use libraries instead of building from scratch

Example: Use an ORM instead of hand-writing SQL, even though raw SQL might be slightly faster. Your programmer can modify it in minutes instead of hours.

15. Rule of Generation: Avoid Hand-Hacking; Write Programs to Write Programs When You Can

The Principle: If you’re doing the same thing repeatedly, write a program to do it. Code generation, templating, configuration files-use these instead of manual repetition.

Why It Matters: Hand-hacked code is full of subtle variations: copy-paste mistakes, inconsistencies, forgotten updates. Generated code is consistent: the pattern is written once and applied everywhere.

In Practice:

• Makefiles and build scripts
• Code generators
• Configuration files
• Templates and scaffolding

Example: Don’t write database access code by hand for each entity. Generate it from a schema. One mistake in the generator is one mistake fixed; one mistake in hand-written code is one mistake per entity.

16. Rule of Extensibility: Design for the Future, Because It Will Be Here Sooner Than You Think

The Principle: Systems outlive your assumptions about them. Design so that the next person (or future you) can add features without rebuilding from scratch.

Why It Matters: Software that served one purpose often needs to serve another. Features that seemed impossible now seem essential. Systems must be designed for adaptation.

In Practice:

• Clean interfaces enable new uses
• Modular design enables new components
• Clear separation of concerns enables new policies
• Documentation of assumptions enables future understanding

Example: When you design a logging system, assume it will need to:

• Write to files
• Write to cloud services
• Be filtered by severity
• Be enriched with context

Design for these possibilities now, even if you don’t need them yet.

17. Rule of Transparency: Design for Visibility to Make Inspection and Debugging Easier

The Principle: System behavior should be observable. You should be able to see what’s happening without guessing or inserting debugging code.

Why It Matters: Debugging invisible systems takes forever. Systems designed for transparency reveal their state and behavior clearly, making problems obvious when they occur.

In Practice:

• Logging at appropriate levels
• Metrics and observability
• Clear state representations
• Explicit error messages
• Debuggable interfaces

Example: A system that logs every significant state change is much easier to debug than a system that requires stepping through a debugger.

18. Rule of Attention: Respect Attention as a Finite Resource

The Principle: Attention is finite. Systems that demand constant vigilance create friction. Design systems that communicate necessary information while respecting user and operator focus.

Why It Matters: Information overload reduces signal-to-noise ratio. When everything is urgent, nothing is. When systems demand constant attention, users disable alerts, miss real problems, or abandon the system entirely.

In Practice:

• Distinguish critical from secondary information
• Alert only when user action is required
• Provide status through non-intrusive channels (icons, colors, optional indicators)
• Silent operation for background work
• Clear, actionable errors that don’t demand constant vigilance
• Graceful degradation when something fails

Example: A sync system that works silently and shows status via an icon is calm. A system that interrupts with modal dialogs for every operation is demanding. Same functionality; vastly different attention cost.

Philosophy: Extending Clarity to Users

See /pb-calm-design for the complete calm design framework and 10-question checklist.

Core insight: The same clarity principle that makes code readable makes interfaces calm. Clarity for engineers means explicit, obvious code. Clarity for users means: “What’s happening?” and “What do I do?” are always obvious.

• For engineers: Clear code prevents bugs, aids debugging, enables modification
• For users: Clear interfaces enable understanding, reduce anxiety, support confidence
• For operators: Clear systems are observable; failures are visible, not hidden

The unified principle: Minimize cognitive load. Whether you’re reading code or using a system, respect that attention is finite. Design accordingly.

Decision Framework: When Rules Conflict

These 17 rules don’t always agree with each other. Understanding the trade-offs is critical.

Common Tensions

Simplicity vs. Robustness

• Simple systems sometimes need complex error handling
• Robust systems sometimes need complex logic

Solution: Use preamble thinking. Surface the trade-off explicitly. Challenge assumptions: “Do we actually need this robustness?” Document the choice so future work understands why.

Clarity vs. Economy

• Explicit code is clearer but longer
• Concise code is shorter but less clear

Solution: Optimize for understanding first. Accept more code if it means clarity. Economy is about not writing unnecessary code, not about writing concise code.

Modularity vs. Performance

• Modular systems have function-call overhead
• Optimized systems sometimes require merging modules

Solution: Measure first (Rule of Optimization). Don’t assume modularity is slow. Only optimize after profiling. Even then, keep the modular design and optimize carefully within it.

Extensibility vs. Simplicity

• Designing for future extensions adds complexity now
• Simple designs don’t anticipate future needs

Solution: Design for extensibility through modularity, not through flexibility. Don’t try to handle all possible futures. Build modules that new code can extend without modifying existing code.

How Rules Apply Across the Playbook

In Planning (/pb-plan, /pb-adr)

• Clarity: ADRs document decisions explicitly
• Representation: Design documents show data structures clearly
• Separation: Separate concerns in the architecture

In Development (/pb-start, /pb-cycle)

• Simplicity: Start simple; add features when needed
• Modularity: Build small, focused pieces
• Optimization: Test first; optimize only if measured

In Review (/pb-review-hygiene, /pb-review-product)

• Clarity: Code is understandable
• Robustness: Error handling is appropriate
• Modularity: Pieces are independent
• Extensibility: Changes can be made without rebuilding

In Operations (/pb-incident, /pb-observability)

• Transparency: Systems are observable
• Repair: Failures are loud and clear
• Simplicity: Operational procedures are straightforward

Examples: Rules in Action

Example 1: API Design (Clarity, Composition, Least Surprise)

Problem: You’re designing an API for user authentication.

Bad Design (Violates Clarity & Least Surprise):

POST /auth with body { user: "...", pass: "..." }
Returns 200 with { token: "...", etc: "..." } on success
Returns 200 with empty body on failure (unclear!)
Token expires silently; caller has no warning

Good Design (Follows Clarity & Least Surprise):

POST /auth with clear request body
Returns 200 with { token, expiresAt, refreshToken }
Returns 401 with { error, errorDescription } on failure
Includes expiresAt so caller can proactively refresh

Rules Applied:

• Clarity: API is obviously correct. No surprises.
• Least Surprise: Errors are clear; expiration is explicit
• Composition: Other systems can easily use this API
• Silence: Success returns just what’s needed

Example 2: Refactoring (Simplicity, Modularity, Repair)

Problem: You have a 500-line function that handles user creation, validation, logging, and error reporting.

Bad Approach (Violates Simplicity & Modularity): Try to optimize the function. Add more error handling. Make it more robust by adding checks everywhere.

Good Approach (Follows Design Rules):

1. Separate validation from creation
2. Separate logging from business logic
3. Separate error handling from happy path
4. Test each piece independently
5. Now you have five simple functions instead of one complex one

Rules Applied:

• Simplicity: Each function is simple
• Separation: Concerns are separate
• Modularity: Each function is independent
• Repair: Errors are clear at each step

Example 3: System Architecture (Separation, Composition, Extensibility)

Problem: You’re designing a notification system (emails, SMS, Slack).

Bad Design (Violates Separation & Modularity): One service handles all notification types. Each new type requires modifying core code. Logic is tangled.

Good Design (Follows Design Rules):

NotificationService (interface)
├── EmailNotification (implementation)
├── SMSNotification (implementation)
└── SlackNotification (implementation)

New notification types extend the interface, don't modify existing code

Rules Applied:

• Separation: Policy (when to notify) from mechanism (how)
• Composition: New types compose into the system
• Modularity: Each implementation is independent
• Extensibility: Adding new types doesn’t touch old code

Example 4: Documentation (Clarity, Representation, Least Surprise)

Problem: You’re documenting a library’s error handling.

Bad Documentation (Violates Clarity): “This function may throw errors. Handle appropriately.”

Good Documentation (Follows Clarity):

Throws ValidationError if input is invalid
Throws TimeoutError if operation exceeds 30 seconds
Throws ConnectionError if database is unavailable
Returns null if resource not found

All errors include error.code and error.message for handling

Rules Applied:

• Clarity: Errors are completely clear
• Representation: Error types encode the problem
• Least Surprise: Caller expects exactly these errors
• Silence: Documentation says only what matters

Example 5: Error Handling (Repair, Transparency, Robustness)

Problem: Your system has a bug where corrupted data silently accumulates.

Bad Response (Violates Repair): Add more error handling downstream hoping to catch it eventually.

Good Response (Follows Design Rules):

1. Add validation at the source (Repair: fail immediately)
2. Add logging so problems are visible (Transparency)
3. Make the corruption obvious, not subtle (Robustness through transparency)
4. Fix the root cause; don’t try to recover silently

Rules Applied:

• Repair: Fail noisily at the source
• Transparency: Log what’s happening
• Robustness: Visible failures are more robust than silent ones

Related Commands

• /pb-preamble - How teams think together (complement to design rules)
• /pb-adr - Architecture decisions document rules
• /pb-patterns - Patterns show rules in practice
• /pb-review-hygiene - Code review checks rules
• /pb-standards - Working principles and code quality

Design Rules - Technical principles that complement preamble thinking and guide every engineering decision.

Project Guidelines & Working Principles

See /pb-preamble and /pb-design-rules first. These standards assume you’re operating from both mindsets:

• Preamble: Challenge assumptions, prefer correctness over agreement, think like peers
• Design Rules: Build systems that are clear, simple, modular, robust, and extensible

Resource Hint: sonnet - Practical standards reference; implementation-level guidance.

When to Use

• Setting up project conventions for a new codebase
• Reviewing code against quality and collaboration standards
• Resolving disagreements about coding practices or workflow norms
• Onboarding team members to working principles

I. Collaboration & Decision Making

Decision Making

• Always Ask Clarifying Questions when input is needed. If a task takes longer than 4 hours to spec out, it requires synchronous discussion.
• Present Available Options with clear Pros/Cons to enable informed choices.
• Make Informed Choices Together: No assumptions without discussion.
• Document Key Decisions (ADR): Use the Architecture Decision Record format to capture the rationale behind major choices (Decisions as Code).

Communication Style

• Be Concise but Thorough: Explain trade-offs clearly and surface ambiguities early.
• Asynchronous First: Use issue tracking for standard tasks; reserve synchronous meetings for high-stakes decisions.
• Propose Recommendations but defer to user/stakeholder judgment on final direction.

II. Strategic Focus & Scope Management

Project Motivation & North Star

• Consult project-description.md: This is the single source of truth for scope. Any feature must directly serve the documented goals.
• Goal: Deliver a clean, practical, self-contained solution demonstrating strong backend engineering and production-ready architecture.
• Anti-Bloat Principle (YAGNI): Focus on real value. Do not implement features or abstract solutions for problems that do not exist yet. Over-engineering is technical debt.

Target Market & Localization

• The primary userbase and workflow is [Country]-centric. All design decisions must prioritize the local ecosystem requirements.

Working Memory & Development Control

• Todos are Dev-Only: The todos/ folder is for development notes only and must be .git-ignored. Never commit temporary files.
• Never add new docs Anything published to docs/ must be confirmed, status report, working docs, ADR can be saved to todos/ for local reviews.
• Time-Boxed Prototyping: Use temporary branches for experiments.
• Task Output: Each task or todo must result in demonstrably working, testable code.

III. Quality Standards & Implementation

Core Quality Standards

• Maintainability Over Complexity: Prefer clean, readable implementation. Code should be easy to delete.
• DRY Principle: Strictly adhere to Don’t Repeat Yourself to minimize knowledge duplication.
• Test Incrementally: Write automated tests (Unit, Integration) concurrently with the code. No significant feature is complete without passing tests.
• Commit Hygiene: Commit small, logical units frequently. Use Conventional Commit format (e.g., feat:, fix:, refactor:) for clear history.

Test Quality Standards

Tests should catch bugs, not chase coverage numbers.

Test What Matters:

• Error handling and edge cases
• State transitions and side effects
• Business logic and security-sensitive paths
• Integration points (API, storage)

Avoid Low-Value Tests:

• Static data validation (config, constants)
• Implementation details / re-implemented internal functions
• Every input permutation (use representative samples)
• Trivial code paths

Maintain Test Health:

• Prune low-value tests periodically
• Speed up slow tests with proper mocking
• Fix or quarantine flaky tests immediately

Accessibility Standards

• Keyboard First: All interactive elements must work with keyboard (Enter/Space for actions)
• Focus Management: Modals trap focus; closing restores focus to trigger
• ARIA Labels: Icon-only buttons need aria-label; decorative icons use aria-hidden
• Visible Focus: Focus rings visible in both light and dark modes
• Touch Targets: Minimum 44x44px for mobile

IV. Technology-Specific Standards

A. Go (Microservices & High Performance)

• Concurrency: Use sync.WaitGroup and context to manage Goroutine lifecycles. Prevent leaks.
• Error Handling: Use errors.Is and errors.As. Do not use panic for expected runtime errors. Wrap errors with context.
• Architecture: Favor Interfaces over concrete types for dependency injection and testability.

B. Node.js (APIs & Event-Driven)

• Async/Await: Never block the Event Loop. Always use async/await for I/O operations.
• Separation of Concerns: Use a layered structure (Controller-Service-Repository). Never put business logic in Express middleware.
• Security: Centralize error handling. Use libraries like Helmet for headers and implement rate limiting.

C. Python (Data & Automation)

• Environment: Always use a Virtual Environment (venv) and lock files.
• Typing: Use Type Hinting extensively (e.g., def func(x: int) -> bool:) to improve readability and tooling support.
• Frameworks: Prefer lightweight frameworks (FastAPI, Flask) for microservices over monolithic structures.

D. Frontend & Mobile Decisions

• Styling: Standardize on Component-Based Styling (CSS Modules, Styled Components, Tailwind). Avoid global stylesheets.
• Data Fetching: Use dedicated libraries (React Query, SWR) for API state management to handle caching and loading states automatically.

V. Live Documentation

Principles

project-description.md is a living document and the authoritative manual.

• Compact & Focused: Document only significant decisions and rationale.
• Actionable: Future developers must understand the “why,” not just the “what.”

Mandatory Update Points

Update documentation after:

• Key design decisions are finalized.
• Architecture changes are implemented.
• New components are added.
• Core patterns are changed.
• Major milestones are completed.

VI. Release Planning & Tracking

Release Structure

Each release (v1.X.0) follows a structured approach:

todos/releases/v1.X.0/
├── 00-master-tracker.md    # Overview, success criteria, changelog
├── phase-1-*.md            # Detailed phase documentation
├── phase-2-*.md            # Tasks, verification, files to modify
└── ...

Phase Documentation

Each phase doc includes:

• Objective - What and why
• Tasks - Specific work items with checkboxes
• Verification - How to confirm completion
• Files to Modify - Concrete list of changes
• Rollback Plan - How to undo if needed

Iterative Workflow

1. Plan - Create master tracker and phase docs
2. Implement - Work through phases, update checkboxes
3. Self-Review - Verify against phase criteria
4. Commit - Logical commits after each task
5. Update Tracker - Mark phases complete, add changelog entries
6. Deploy - Tag release, deploy, verify

Tracker Maintenance

• Update phase status as work progresses
• Add changelog entries for significant work
• Mark Definition of Done items when complete
• Document deferred items for next release

VII. Quality Bar: Minimum Lovable

Design Rules tell you how to build. This tells you when you’re done.

The MLP Criteria

Before declaring work complete, ask:

• Would you use this daily without frustration? - Not just functional, but pleasant
• Can you recommend it without apology? - “It works, but…” means it’s not done
• Did you build the smallest thing that feels complete? - Scope discipline, not scope creep

If any answer is “no”: keep refining. If all are “yes”: ship it.

Calm Quality Bar (v2.12.0)

Extend the MLP criteria with attention-respect:

• Does this respect user attention? - Works silently? Alerts only when critical? Optional instead of mandatory?
• Are errors clear and recoverable? - User knows what went wrong and what to do next?
• Does this fail gracefully? - Does it degrade to partial functionality, or does it break completely?
• Would you use this daily without thinking about it? - Does it recede into the background?

See /pb-calm-design for the complete 10-question calm design checklist and philosophy.

What MLP Is Not

• Feature-rich - MLP is about care, not quantity
• Polished to perfection - Good enough to love, not flawless
• Over-engineered - Simplicity is part of lovability

The Mindset Shift

MLP is a discipline, not a milestone. Build less. Care more.

VIII. SDLC Discipline & Code Quality Commitment

Our Commitment

We commit to bug-free, rock-solid results through disciplined adherence to a full Software Development Life Cycle. Every iteration, regardless of size, follows the same rigorous process. We do not cut corners.

Development Workflow

Start work: /pb-start - Creates feature branch, establishes iteration rhythm

Each iteration: /pb-cycle - Guides through develop → self-review → peer review → commit

Release: /pb-release - Pre-release checks, deployment

Iteration Cycle (Mandatory for All Changes)

┌─────────────────────────────────────────────────────────────┐
│  1. DEVELOP      Write code following standards             │
│         ↓                                                    │
│  2. SELF-REVIEW  Review your own changes critically         │
│         ↓                                                    │
│  3. TEST         Verify: lint, typecheck, tests pass        │
│         ↓                                                    │
│  4. PEER REVIEW  Get feedback on approach and quality       │
│         ↓                                                    │
│  5. COMMIT       Logical, atomic commit with clear message  │
└─────────────────────────────────────────────────────────────┘

Run /pb-cycle for detailed checklists at each iteration.

Quality Gates

Run after each iteration:

make lint        # Lint check passes
make typecheck   # Type check passes
make test        # All tests pass

All gates must pass before proceeding. Fix issues immediately.

Commit Discipline

• One concern per commit - Each commit addresses a single feature, fix, or refactor
• Always deployable - Every commit leaves the codebase working
• Conventional format - Use feat:, fix:, refactor:, docs:, test:, chore: prefixes
• Never use git add . - Add specific files that belong together

Commit timing: After each meaningful unit of work, not at end of session.

The Non-Negotiables

• Never ship known bugs - Fix or explicitly defer with ticket
• Never skip testing - Manual QA minimum, automated preferred
• Never ignore warnings - Warnings become bugs
• Never “just push it” - Every change deserves the full cycle

Quick Reference

Related Commands

• /pb-preamble - Collaboration philosophy (mindset)
• /pb-design-rules - Technical principles (clarity, simplicity, modularity)
• /pb-guide - Master SDLC framework
• /pb-commit - Atomic commit practices
• /pb-testing - Test patterns and strategies

Core Engineering SDLC Framework (Language-Agnostic)

A reusable end-to-end guide for any feature, enhancement, refactor, or bug fix. Right-size your process using Change Tiers, then follow required sections.

Mindset: This framework assumes you’re operating from both /pb-preamble (how teams think) and /pb-design-rules (what systems should be).

Challenge the tiers, rearrange gates, adapt to your team-this is a starting point, not dogma. Every gate should verify design rules are being honored, not just that work is complete.

Resource Hint: sonnet - Structured process reference; implementation-level guidance.

When to Use

• Starting any new feature, enhancement, refactor, or bug fix
• Determining the right change tier and required process gates
• Onboarding team members to the development lifecycle
• Reviewing whether your process matches the scope of the change

Quick Reference: Change Tiers

Determine tier FIRST, then follow only required sections.

Default to one tier higher if uncertain.

Definition of Ready (Before Starting)

Before starting implementation, confirm:

• Tier determined and documented
• Scope documented (in-scope / out-of-scope)
• Acceptance criteria defined and agreed
• Dependencies identified and unblocked
• Security implications assessed (see Appendix A)

Definition of Done (Before Release)

Before marking complete:

• All acceptance criteria met
• Tests passing (per tier requirements)
• Security checklist completed (Appendix A)
• Documentation updated (if applicable)
• Monitoring/alerting configured (M/L tiers)
• PR approved and merged
• Deployed and smoke tested

Checkpoints & Gates

Do not proceed past a gate without sign-off.

0. Emergency Path (Hotfixes Only)

For P0/P1 production incidents requiring immediate fixes:

Process:

1. Fix the immediate problem (minimal change)
2. Get expedited review (sync, not async)
3. Deploy with rollback ready
4. Backfill documentation within 24 hours
5. Schedule post-incident review

Required: §1.1 (brief), §5.2, §8.2 (rollback), §10.2, §10.3

Skip: §2 (most), §4 (most), §9

Post-hotfix: Create follow-up ticket to address root cause properly.

1. Intake & Clarification

Before starting any work:

1.1 Restate the request

Document:

• What is asked
• Why it matters (business value)
• Expected outcome
• Success criteria (measurable)
• Assumptions requiring validation
• Tier assignment (XS/S/M/L)

1.2 Clarification checklist

Ask for details on:

• Missing acceptance criteria
• Ambiguities in requirements
• Conflicting requirements
• Third-party constraints
• Dependencies on other teams or systems

If anything is unclear, stop and clarify.

2. Stakeholder Involvement & Alignment

Required for: M, L tiers

Every significant change needs validation from multiple angles.

2.1 Product

• Confirm user story
• Confirm acceptance criteria
• Define measurable success metrics
• Check interactions with existing features
• Confirm visual/UI/UX expectations (if applicable)

2.2 Engineering (Backend, Frontend, Infra)

• Impact on architecture
• Data flow changes
• Service boundary / API changes
• Storage requirements
• Observability needs
• Performance expectations

2.3 Business & Operations

• Risk assessment
• Compliance (PII, audit, GDPR if applicable)
• Revenue or cost implications
• Customer impact and rollout timing

Output: Single aligned understanding documented before proceeding.

3. Requirements & Scope Definition

Required for: S, M, L tiers

Create a clear boundary so the team knows what to deliver.

3.1 In-scope Everything this change must include.

3.2 Out-of-scope Anything explicitly excluded to avoid scope creep.

3.3 Edge cases List special scenarios: failures, retries, degraded modes, empty states.

3.4 Dependencies

• API or service dependencies
• Schema updates
• External systems
• Libraries/packages
• Feature flag or config dependencies

CHECKPOINT: Scope Lock (M/L tiers) - Get sign-off before proceeding.

4. Architecture & Design Preparation

Required for: M, L tiers

Provide a solid technical foundation.

4.1 High-level architecture Include:

• Diagrams (flow, sequence, state as needed)
• Inputs, outputs, transformations
• Error pathways
• Retry/timeout/circuit breaker behavior

Async & Distributed Patterns

For async and distributed system patterns, see dedicated guides:

• /pb-patterns-async - Callbacks, Promises, async/await, job queues, worker pools
• /pb-patterns-distributed - Saga, event sourcing, CQRS, eventual consistency

Key decision: Choose async patterns based on coupling requirements:

• Tight coupling needed: Synchronous calls, 2PC
• Loose coupling preferred: Events, Sagas, message queues

Pattern selection:

4.2 Data Model Design

• Schema updates
• Indexing strategy
• Backward compatibility
• Migration approach (online/offline, rollout steps)

4.3 API/Interface Design

• Request/response format
• Error codes and messages
• Pagination, filtering, sorting
• Idempotency requirements
• Compatibility with existing consumers

4.4 Performance & Reliability

• Expected load
• Stress points
• Concurrency handling
• Latency targets
• Resource usage (CPU, RAM, DB connections)

4.5 Security Design Reference Appendix A: Security Checklist and document:

• How each applicable item is addressed
• Any security trade-offs or accepted risks

CHECKPOINT: Design Approval (M/L tiers) - Get tech lead sign-off.

5. Development Plan

Required for: S, M, L tiers

Break work into implementable steps.

5.1 Implementation roadmap

For each component:

• Backend tasks
• Frontend tasks
• Infra tasks
• Data migration tasks
• Monitoring/logging tasks

5.2 Coding practices

Follow standards:

• Clean, readable structure
• Type safety
• Error handling with context
• Proper logging (no sensitive data)
• Retry & timeout patterns
• Minimize duplication
• Graceful degradation paths

5.3 Developer checklist

Before marking code complete:

• Handle success path
• Handle failure paths
• Handle malformed/unexpected inputs
• Handle concurrency and race conditions
• Add cleanup logic where needed
• Add idempotency where needed
• Confirm testability

5.4 Iteration protocol

During implementation, if scope or design changes are needed:

• Minor adjustment: Document in PR description, proceed
• Significant change: Return to §3 or §4, get re-approval before continuing

Don’t silently expand scope.

CHECKPOINT: Ready for QA - Self-review complete.

6. Testing & Quality Assurance

Required for: S, M, L tiers (scope varies by tier)

6.1 Test Philosophy: Quality Over Quantity

Tests should catch bugs, not just increase coverage numbers.

DO Test:

• Error handling and edge cases
• State transitions and side effects
• Business logic and calculations
• Integration points (API calls, storage)
• Security-sensitive paths (auth, validation)

DON’T Test:

• Static data structures (config, constants)
• Implementation details / internal functions
• Every permutation of valid inputs
• UI rendering details (prefer visual regression or E2E)
• Trivial getters/setters

Anti-patterns to avoid:

• Re-implementing internal functions in test files to test them
• Testing that data exists (instead of testing behavior)
• Over-parameterized tests for diminishing returns
• Slow integration tests that should be unit tests

6.2 Test requirements by tier

6.2a Integration Testing

For comprehensive integration testing patterns, see /pb-testing:

• Database fixtures and factories
• Test isolation strategies
• Docker Compose for test dependencies
• Testcontainers patterns
• CI/CD test configuration

Key point for M/L tier: Test component interactions (API → DB, Service A → Service B). Isolate each test with fresh state. Mock external services, use real databases.

6.3 Test types reference

• Unit tests - Isolated function/method testing
• Integration tests - Component interaction testing
• End-to-end tests - Full user flow testing
• API contract tests - Request/response validation
• Regression tests - Ensure existing functionality unbroken
• Negative tests - Invalid inputs, error conditions
• Load tests - Performance under expected/peak load

6.4 QA scenarios (M/L tiers)

Document actual test cases covering:

• Happy path
• Alternate flows
• Error scenarios
• State transitions
• Data consistency checks
• Frontend usability (if applicable)

6.5 Test data

Create controlled, realistic test datasets. Never use production PII.

6.6 Test maintenance

Periodically review test suite for:

• Low-value tests to prune (static data tests, over-parameterized tests)
• Slow tests to speed up (missing mocks, over-integrated)
• Flaky tests to fix or quarantine
• Coverage gaps in critical paths

Target: Fewer, faster, more meaningful tests.

CHECKPOINT: Ready for Release (M/L tiers) - QA sign-off.

7. Infra, Deployment & Security Readiness

Required for: M, L tiers (7.1 always; 7.2-7.3 for L)

7.1 Infrastructure changes

• New services or containers
• New environment variables
• New storage (DB, cache, files)
• New queues/topics
• Additional monitoring or logs

7.2 Security hardening

Reference Appendix A and confirm:

• All applicable items addressed
• No new attack surfaces introduced
• Secrets properly managed

7.3 Observability

• New dashboards needed?
• Alert rules defined?
• Log retention configured?
• SLO metrics identified?

8. CI/CD Requirements