---
name: sa-playbook
description: |
  This skill should be used when the user asks to "design a system",
  "create an architecture", "write an ADR", "do solution architecture",
  "architect a solution", "review my architecture", "SA task",
  "stakeholder analysis", "trade-off analysis", "C4 diagram",
  "non-functional requirements", "NFR", "architecture decision record",
  or mentions solution architecture work. Guides developers and tech leads
  through SA tasks using SFIA 9 framework with a 5-phase workflow
  (Discover → Define → Design → Decide → Deliver), inline coaching,
  and architecture assessment.
  Do NOT use for: code-level design patterns, CI/CD pipeline setup,
  or infrastructure provisioning (Terraform/Pulumi).
---

# SA Playbook v1.0

Guides developers and tech leads through Solution Architecture tasks using the SFIA 9 framework. Combines a phase-based workflow with inline coaching to build SA competency from SFIA level 4 (Enable) toward level 5-6.

## Core Principles

1. **Hybrid guidance** — Walk through SA phases together, not just instruct. Recommend patterns, draft artifacts collaboratively, and help complete the task.
2. **SFIA-mapped coaching** — Every activity maps to a SFIA skill and level. Inline coaching explains what skill is being practiced and how to level up.
3. **Flexible phases** — 5 phases provide structure, but skip or jump as context demands. No forced quality gates.
4. **Artifacts over theory** — Each phase produces concrete deliverables (stakeholder maps, ADRs, C4 diagrams), not just checklists.
5. **YAGNI first** — Always challenge: "Is this truly needed at the current scale?" Design for separation, deploy simply. Avoid over-engineering.
6. **SA does not own the roadmap** — SA provides the dependency map and readiness milestones. Timeline decisions are made by the PO based on business priorities.

## SA Workflow — 5 Phases

| # | Phase | Purpose | Key SFIA Skills | Key Artifacts |
|---|-------|---------|-----------------|---------------|
| 1 | **Discover** | Understand context, stakeholders, constraints | BUSA, REQM | Stakeholder map, Context doc |
| 2 | **Define** | Formalize requirements, NFRs, boundaries | REQM, DATM, SCTY | Requirements doc, NFR matrix |
| 3 | **Design** | Create architecture, evaluate trade-offs | ARCH, DESN, NTDS, DBDS, DTAN | C4 diagrams, Component specs, Trade-offs |
| 4 | **Decide** | Validate decisions, get buy-in | TECH, CNSL, ARCH | ADRs, Risk assessment |
| 5 | **Deliver** | Document, communicate, handoff | ARCH, METL | Architecture doc, Dependency map, Milestones, Presentation |

For detailed phase activities, coaching prompts, and artifact guidance, consult `references/sa-phases.md`.

## Session Management

### Starting a Session

When the user initiates an SA task:

1. Generate session ID: `SA-{PROJECT}-{YYYYMMDD}-{SEQ}` (derive PROJECT from directory name)
2. Create workspace: `.sa-playbook/sessions/{session_id}/`
3. Initialize `state.yaml` with phase tracking
4. Begin at the appropriate phase (default: Discover)

### State File

```yaml
session_id: SA-{PROJECT}-{YYYYMMDD}-{SEQ}
current_phase: discover
phases:
  discover: { status: in_progress, artifacts: [] }
  define: { status: not_started, artifacts: [] }
  design: { status: not_started, artifacts: [] }
  decide: { status: not_started, artifacts: [] }
  deliver: { status: not_started, artifacts: [] }
coaching_log: []
```

### Workspace Structure

```
.sa-playbook/sessions/{session_id}/
├── state.yaml
├── discover/
├── define/
├── design/
│   └── adrs/
├── decide/
└── deliver/
```

### Phase Navigation

- **Skip**: If requirements already exist, skip Discover/Define and start at Design
- **Jump back**: Return to any previous phase to refine artifacts
- **Resume**: Read `state.yaml` to continue where left off

## Inline Coaching

At key moments (artifact completion, design decisions, phase transitions), provide coaching:

```
> **SA Coach** (ARCH L4 → L5)
> [Observation about current work]
> [Tip for next-level performance]
```

Coaching guidelines:
- Map each activity to its SFIA skill code and level
- Show what the current level requires AND what the next level looks like
- Coach at meaningful moments, not every step
- Keep coaching concise (2-3 sentences)

For coaching prompt templates by skill and level, consult `references/coaching-prompts.md`.

## Architecture Assessment

When reviewing an architecture document (via `/sa:assess` or during a session):

1. Read the document
2. Evaluate against SFIA criteria for each relevant skill
3. Score on 4 dimensions: **Completeness**, **Depth**, **Communication**, **Decision quality**
4. Report estimated SFIA level per skill, strengths, gaps, and recommendations

For the full assessment rubric, consult `references/assessment-criteria.md`.

## SFIA Skill Reference

The primary SFIA skills for SA work and their phase mapping:

| Skill | Code | Primary Phases |
|-------|------|---------------|
| Solution architecture | ARCH | Design, Decide, Deliver |
| Systems design | DESN | Design |
| Requirements definition | REQM | Discover, Define |
| Data management | DATM | Define, Design |
| Data modelling and design | DTAN | Design |
| Network design | NTDS | Design |
| Database design | DBDS | Design |
| Specialist advice | TECH | Decide |
| Methods and tools | METL | All phases |
| Business situation analysis | BUSA | Discover |
| Information security | SCTY | Define, Decide |
| Consultancy | CNSL | Decide, Deliver |

For full SFIA skill descriptions at each level, consult `references/sfia-skill-map.md`.

## Artifact Templates

When creating artifacts, use the templates in `references/artifact-templates.md`. Templates include:
- Stakeholder map
- Context document
- NFR matrix
- C4 diagram descriptions
- Architecture Decision Record (ADR)
- Trade-off analysis
- Technical dependency map
- Architecture readiness milestones
- PO decision matrix
- Architecture document (final)

## Architecture Patterns

When selecting architectural approaches, consult `references/architecture-patterns.md` for common patterns with trade-off analysis:
- Deployment: Monolith vs Microservices vs Hybrid
- Data isolation: RLS vs Schema vs Dedicated DB
- Knowledge management: Clone vs Reference vs Real-time sync
- Access control: Restricted vs Open with guardrails
- Config storage: Filesystem vs DB vs Hybrid

## Level Progression

Target audience: Dev/Tech Lead → SA (SFIA Level 4), with growth path:

- **Level 4 (Enable)** — Contribute to architecture, identify trade-offs, document decisions
- **Level 5 (Ensure, advise)** — Lead architecture development, provide governance, ensure standards
- **Level 6 (Initiate, influence)** — Establish policies, manage cross-project architecture

## Additional Resources

### Reference Files

- **`references/sa-phases.md`** — Detailed phase activities, conversation guides, artifact checklists
- **`references/sfia-skill-map.md`** — Full SFIA skill descriptions for SA-relevant skills at each level
- **`references/coaching-prompts.md`** — Coaching templates organized by skill and level transition
- **`references/artifact-templates.md`** — Ready-to-use templates for all SA artifacts (including dependency map, milestones, PO matrix)
- **`references/assessment-criteria.md`** — Full rubric for architecture assessment scoring
- **`references/architecture-patterns.md`** — Common architectural patterns with YAGNI-first trade-off analysis