Menu
Use when mapping all actors in a service ecosystem — who serves whom, dependencies, interest alignment and conflict, power dynamics
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 | stakeholder-map |
| description | Use when mapping all actors in a service ecosystem — who serves whom, dependencies, interest alignment and conflict, power dynamics |
Core principle: The blueprint shows one actor's path; the stakeholder map shows how all actors connect. Staff experience drives customer experience — the service-profit chain is not optional.
Scan code, org charts, interviews, business docs. Code reveals roles/permissions. Org charts reveal reporting. Interviews reveal informal structure.
| Type | What to look for |
|---|---|
| Customer | User roles, signup flows, segments |
| Frontline | Customer-facing staff, support agents, account managers |
| Backstage | Operations, fulfillment, moderation, internal tooling users |
| Support/Ops | Engineering, finance, legal, HR — enabling systems |
| External | Partners, vendors, payment processors, regulators |
For every actor pair, capture four dimensions:
| Dimension | Question |
|---|---|
| Serves | Who delivers value to whom? |
| Depends on | Who blocks whom when they fail? |
| Information flow | What data/signals pass between them? |
| Handoff risk | Where do things drop? |
Trace from code (API calls, queues, mailers, webhooks) and operations (escalations, emails). Code shows designed flows; interviews reveal workarounds.
Identify where interests align and where they conflict (metrics rewarding one actor at another's expense). Misalignment is where failures originate — a frontline team measured on handle time cuts corners, creating backstage rework and customer frustration.
Document decision authority, veto power, and affected-but-voiceless actors. Services optimize for the most powerful actor by default. Name who benefits and who bears costs.
Map actors to each link: internal service quality (tools, training, autonomy) → employee satisfaction → service delivery quality → customer satisfaction → revenue/growth. If internal quality is poor, no customer-facing design fixes it. Tag each link.
Accept code, org charts, transcripts, support tickets, business docs. Cross-reference — a code role absent from the org chart is a finding; an interview actor absent from code is a gap.
Tag every claim [confirmed], [hypothesis], or [gap]. For each hypothesis, note what would confirm it.
Write to docs/service-design/<slice>/stakeholder-map.md using the template at service-design/templates/stakeholder-map.md. Use project-wide when mapping the full ecosystem.
Run AFTER service-design:actor-profile (needs actors defined). Run BEFORE service-design:service-blueprint (informs backstage/support lanes) and service-design:service-diagnosis (misalignment causes failures).
