Menu
Use when mapping how a service actually works — frontstage/backstage/support lanes from code, docs, and operational knowledge
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when writing Rails controllers or implementing state changes - enforces resource extraction, thin controllers delegating to models, params.expect, and controller concerns for scoping
Use when designing database schema, writing migrations, or making data storage decisions - enforces UUIDs, account_id multi-tenancy, no foreign keys, and proper index patterns
Use when writing Hotwire (Turbo/Stimulus) code in Rails - enforces dom_id helpers, morph updates, focused Stimulus controllers, and JavaScript private methods
Use when writing background jobs or async operations - enforces thin job wrappers (3-5 lines) that delegate to models using _later/_now naming pattern
Use when writing Rails models - enforces state-as-records not booleans, concerns as adjectives namespaced under model, and concern extraction triggers
Use when naming classes, methods, routes in vanilla Rails codebases - enforces concern adjectives (-able/-ible only), no bangs for state, resource naming cascade, and commit message format
| name | service-blueprint |
| description | Use when mapping how a service actually works — frontstage/backstage/support lanes from code, docs, and operational knowledge |
Core principle: A blueprint connects what users experience to what the organization produces. Touchpoints are commitments, not screens.
Read routes, controllers, models, mailers, and jobs to extract the operational backbone: customer actions, frontstage responses, backstage processes, support systems. Code reveals what happens; it cannot reveal what it feels like or why the org chose this shape. Ask targeted questions for those layers. Accept docs, transcripts, and URLs as supplementary sources — ingest them, don't summarize them.
Pick one scenario and one actor. Define start and end conditions from the actor's POV. Combine three lenses to find the right boundary:
| Lens | What it prevents |
|---|---|
| Lifecycle sequencing (pre/during/post) | Optimizing one moment while degrading the surrounding system |
| Context of use (environment, stakes, frequency) | Designing for a user who doesn't exist |
| JTBD forces (functional, social, emotional) | Reducing the service to task completion |
| Line | What it reveals |
|---|---|
| Interaction | Where the user touches the org — every crossing is a moment of truth |
| Visibility | What's hidden vs. shown — a design choice, not just operational fact |
| Internal interaction | Where bottlenecks and systemic failures hide |
Tag every claim: [confirmed] (verified in code or docs), [hypothesis] (inferred from patterns), or [gap] (unknown). Separate observation from inference. For each hypothesis, note what would confirm it — a stakeholder interview, a log query, a support ticket search.
Write to docs/service-design/<slice>/blueprint.md using the template at service-design/templates/blueprint.md. Populate the Service Slice table, Blueprint Lanes, Moments of Truth, and Failure Modes sections.
service-design:empathy-analysis produces the emotional/informational layer this blueprint references. service-design:journey-map sequences the same service across time and channels. Use all three for a complete picture.
