mirror of
https://github.com/deanpeters/Product-Manager-Skills.git
synced 2026-09-14 20:06:57 +08:00
Adornment Plan 4, Wave 4: the tail — 13 skills, 18 files
Ten second-domain examples: - jobs-to-be-done, pol-probe, user-story-mapping, user-story-splitting (Northfield): two job performers who share a product and share no jobs; probes that are physical because you cannot ship a fake door to a plant floor; a backbone spanning days, sites, and organizations; and why the component split is especially costly when firmware release windows are infrequent - pestel-analysis, recommendation-canvas, company-research (Brightwater): Legal as the gating category rather than context; an AI line drawn on accountability rather than accuracy; and zero revenue read as a finding, not a red flag - product-sense-interview-answer: a diagnostic question, structurally opposite to the existing improvement question - the pair exists to teach that using the wrong shape is the failure mode - altitude-horizon-framework, executive-onboarding-playbook: career skills vary org shape, not industry. Horizon set by supply chain lead times; a product org that is not the company's main event Three Group A skills completed: - stakeholder-identification, stakeholder-mapping: templates plus both domains. Both examples land the most-affected, least-powerful group in Monitor on the first grid and correct it on the second, which suggests the mismatch is structural - skill-authoring-workflow: template plus one worked example (meta-skill carve-out), documenting a real build where Preflight nearly stopped it Plan 4 COMPLETE. Single-domain gap 21 -> 0 excluding the three documented carve-outs. Every Component and Workflow skill now ships a template and two-domain examples. Guardrail verified across all Brightwater files. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Dean Peters
@@ -1,6 +1,20 @@
|
||||
# Adornment Plan 4 — Back-Catalog Backfill
|
||||
|
||||
**Status:** Approved Aug 10, 2026. Not started.
|
||||
**Status:** ✅ **COMPLETE — Aug 10, 2026.** All four waves shipped.
|
||||
|
||||
**Final state:** every Component and Workflow skill in the library ships a `template.md` and
|
||||
worked examples from two business domains, except the three documented carve-outs below.
|
||||
Verified by sweep: 1 skill without examples (`finance-metrics-quickref`, carve-out) and
|
||||
1 single-domain (`skill-authoring-workflow`, carve-out).
|
||||
|
||||
| Wave | Scope | Result |
|
||||
|---|---|---|
|
||||
| 1 | 4 template-only fixes | ✅ |
|
||||
| 2 | 7 core artifacts | ✅ |
|
||||
| 3 | 4 workflows | ✅ Brightwater debuts |
|
||||
| 4 | 10 single-domain + 3 Group A | ✅ |
|
||||
|
||||
Single-domain gap: **21 → 0** (excluding carve-outs).
|
||||
**Predecessor:** `docs/maintenance/2026-07-17-adornment-and-docs-plan.md` (Plans 1-3, shipped)
|
||||
|
||||
Bring the back catalog up to the "fully adorned" standard in CLAUDE.md: every Component and
|
||||
|
||||
@@ -0,0 +1,112 @@
|
||||
# Altitude & Horizon Example — Hardware Org
|
||||
|
||||
The `sample.md` example follows a Director in a SaaS company. This one follows the same transition
|
||||
in a **hardware organization** — Northfield Automation, which builds retrofit control systems.
|
||||
|
||||
**Why the org shape matters more than the industry:** altitude and horizon are shaped by how far
|
||||
ahead your organization is forced to think. In SaaS a Director's horizon is quarterly because
|
||||
releases are continuous. In hardware, tooling lead times and certification windows push the
|
||||
planning horizon out to eighteen months *whether or not the Director is ready for it* — and the
|
||||
most common failure is a newly promoted Director still operating on a release-cycle horizon.
|
||||
|
||||
---
|
||||
|
||||
## Example 1: Cascading Context Map in a hardware org
|
||||
|
||||
### Scenario
|
||||
|
||||
Priya was promoted from PM to Director of Product at Northfield six months ago. Company leadership
|
||||
has stated a priority: *"Consolidate onto one control platform by 2028."* Her three teams — platform
|
||||
firmware, I/O modules, and service tooling — have been asking what that means for their work.
|
||||
Nobody above her has translated it.
|
||||
|
||||
### Completed Context Cascade
|
||||
|
||||
```markdown
|
||||
## Context Cascade: Control Platform Group — FY2027
|
||||
|
||||
**Company Priority:** "Consolidate onto one control platform by 2028."
|
||||
|
||||
**Business Unit Translation:** Controls BU stops investing in NFA-200 capability and
|
||||
moves the installed base to NFA-500 without losing service revenue during the wind-down.
|
||||
|
||||
**Product Portfolio Translation:** NFA-500 must cover the full range the NFA-200 covered —
|
||||
including the high-channel-count jobs it currently can't — before we can stop selling
|
||||
the 200.
|
||||
|
||||
**Team Accountabilities:**
|
||||
- Platform firmware: remote update and fault isolation, so a growing installed base is
|
||||
serviceable without a growing field team
|
||||
- I/O modules: close the high-channel-count gap. This is the gate on End of Sale.
|
||||
- Service tooling: migration and commissioning tooling so integrators can move without
|
||||
re-learning everything
|
||||
|
||||
**Why this matters:** the End of Sale date is not ours to move — manufacturing needs the
|
||||
line. What IS ours is whether customers have somewhere to land when it happens.
|
||||
|
||||
**What I'm still unsure about:** whether "one platform by 2028" includes the SmartLink
|
||||
gateway or only controllers. I've asked; I don't have an answer. Planning as if it's
|
||||
controllers only, and I'll say so if that changes.
|
||||
```
|
||||
|
||||
### Why this is strong
|
||||
|
||||
- **It translates a slogan into three team accountabilities**, each traceable to the company line.
|
||||
- **It names the gate.** "This is the gate on End of Sale" tells the I/O module team their work
|
||||
paces everyone else's — the single most useful sentence for a team that would otherwise optimize
|
||||
locally.
|
||||
- **It names what's fixed and what's theirs.** The EOS date is immovable; the landing place is
|
||||
theirs. That's the difference between a team feeling steamrolled and a team feeling accountable.
|
||||
- **The unresolved question is stated, with a working assumption.** Priya didn't wait for clarity
|
||||
and didn't manufacture it. Both are Director behaviors; waiting is the PM habit.
|
||||
- **It fits on one page** for a group spanning three teams and an eighteen-month horizon.
|
||||
|
||||
---
|
||||
|
||||
## Example 2: Anti-Pattern — the horizon that didn't move
|
||||
|
||||
### Scenario
|
||||
|
||||
Six weeks earlier, Priya's I/O module team hit a supplier problem on a component for the
|
||||
high-channel-count module. Her instinct — a good PM instinct — was to dig in: get on calls with the
|
||||
supplier, evaluate substitutes, rebuild the schedule.
|
||||
|
||||
### Director response (weak)
|
||||
|
||||
She spent three weeks largely inside that problem. She was effective; the substitute part was
|
||||
found and the schedule was rebuilt.
|
||||
|
||||
**What it cost:** during those three weeks, the tooling decision for the module housing went
|
||||
unmade. The tooling vendor's August slot was given to another customer. The module — the gate on
|
||||
End of Sale — slipped a full quarter, which pushed the EOS date the company had already committed
|
||||
to manufacturing.
|
||||
|
||||
### What the framework says
|
||||
|
||||
- **Altitude:** she operated at feature/team level on a component sourcing problem her senior PM
|
||||
could have run with support
|
||||
- **Horizon:** she spent a sprint-shaped three weeks while the decision that mattered lived on a
|
||||
14-week lead time. **The horizon failure is the expensive one.** In SaaS, three weeks of Director
|
||||
attention in the weeds costs three weeks. Here it cost a year, because the thing she wasn't
|
||||
watching had a lead time.
|
||||
- **Hero Syndrome trigger:** a hard, concrete, solvable problem — exactly the kind that feels like
|
||||
contribution — appearing while the important decision was ambiguous and slow.
|
||||
|
||||
### Stronger response
|
||||
|
||||
Assign the supplier problem to the senior PM with a clear escalation trigger. Spend her own time on
|
||||
the tooling decision, because it is the one with an external clock she can't restart and no one
|
||||
below her has the authority to make.
|
||||
|
||||
---
|
||||
|
||||
## What this example teaches that the SaaS one can't
|
||||
|
||||
- **Horizon is set by your supply chain, not your calendar.** A Director's planning horizon in
|
||||
hardware is defined by the longest external lead time in the portfolio, and it doesn't wait for
|
||||
the Director to grow into it.
|
||||
- **Hero Syndrome is more expensive when lead times are long.** The same three weeks of misplaced
|
||||
attention costs three weeks in SaaS and a year here.
|
||||
- **"What's fixed vs. what's ours" is the most valuable line in the cascade.** When a date is
|
||||
genuinely immovable, saying so — and naming what the team *does* control — is what keeps a team
|
||||
accountable rather than resentful.
|
||||
@@ -0,0 +1,111 @@
|
||||
# Company Research Example — Life Sciences
|
||||
|
||||
A research brief on **Brightwater Biologics**, a clinical-stage biotech, prepared by a PM ahead of
|
||||
an interview for a product role on its Trialpath platform team.
|
||||
|
||||
**Why this domain changes the research:** a biotech's public record is unusually rich — trial
|
||||
registries, regulatory filings, conference presentations — and unusually misleading if you read it
|
||||
as a software company. Revenue may be zero by design. Headcount growth may signal a trial phase,
|
||||
not commercial traction. The signals mean different things.
|
||||
|
||||
---
|
||||
|
||||
```markdown
|
||||
## Executive Insights Company Profile: Brightwater Biologics
|
||||
|
||||
### 1. What This Entity Is
|
||||
Clinical-stage biotech developing therapies in a specialty indication. Pre-commercial:
|
||||
no approved product, no product revenue. Funded by venture rounds and a partnership.
|
||||
~180 employees, roughly a quarter in clinical operations.
|
||||
[FACT — company site, public funding announcements]
|
||||
|
||||
### 2. How It Makes Money
|
||||
It does not, yet. Capital comes from investors and partnership milestones. The economic
|
||||
model is: spend years generating evidence, then either commercialize or license.
|
||||
[FACT — funding disclosures]
|
||||
|
||||
**Why this matters for a PM:** every internal product competes with the trial program
|
||||
for the same capital. "Is this worth building" is really "is this worth NOT spending on
|
||||
the program." [INFERENCE]
|
||||
|
||||
### 3. Who It Serves
|
||||
Two distinct populations. Externally: patients, investigators, regulators.
|
||||
Internally, for Trialpath: study coordinators at sites, CRA monitors, CRO partners.
|
||||
The internal users do not work for Brightwater — sites are independent organizations.
|
||||
[FACT — trial registry lists participating sites]
|
||||
|
||||
### 4. What It Sells or Delivers
|
||||
Currently: evidence. The deliverable is a data package that supports a regulatory
|
||||
submission. Trialpath exists to make producing that package faster and cleaner.
|
||||
[INFERENCE from the trial-stage profile]
|
||||
|
||||
### 5. Key Product Lines
|
||||
- Lead therapeutic program (the company's actual product)
|
||||
- Trialpath, internal platform — recently the subject of external licensing interest
|
||||
[FACT — job postings reference "platform productization"]
|
||||
|
||||
### 6. Business and Market Pressures
|
||||
- Trial timelines drive everything; a delayed readout moves the funding calendar
|
||||
- Site staffing shortages slow enrollment industry-wide
|
||||
- Small-sponsor funding is rate-sensitive
|
||||
[FACT/INFERENCE mix — see sources]
|
||||
|
||||
### 7. Competitors and Alternatives
|
||||
For the therapy: other programs in the indication. For Trialpath: incumbent trial
|
||||
platforms, and the status quo of spreadsheets plus email at small sponsors.
|
||||
[INFERENCE — no public statement on platform competitors]
|
||||
|
||||
### 8. Important Trends and Risks
|
||||
- Decentralized trial designs shifting coordinator workflows
|
||||
- AI-assisted document review maturing, regulatory acceptability unsettled
|
||||
- **Concentration risk:** one lead program. A trial setback is a company event, and the
|
||||
platform team's funding is downstream of it [INFERENCE — high confidence]
|
||||
|
||||
### 9. Strategic Signals
|
||||
- **Hiring:** three product roles posted in six months, all platform-facing, none
|
||||
therapeutic. Language emphasizes "multi-tenant" and "validation documentation"
|
||||
[FACT — job postings, dated]
|
||||
- **Leadership:** a VP Product hired last year from a trial software vendor, not from
|
||||
pharma [FACT — public announcement]
|
||||
- **Conference activity:** presentations focus on operational efficiency, not
|
||||
clinical results — consistent with a program in an interim period [INFERENCE]
|
||||
|
||||
**Read together:** a hire from a software vendor, plus "multi-tenant" and "validation
|
||||
documentation" in postings, plus operational-efficiency messaging, suggests Trialpath
|
||||
productization is being seriously explored rather than idly considered. [INFERENCE —
|
||||
three independent signals converging]
|
||||
|
||||
### 10. What This Means for Product Management
|
||||
- You would be building for users employed by other organizations. Access is scheduled,
|
||||
bounded, and mediated by site leadership
|
||||
- Validation documentation is likely the gating work item, not a compliance follow-up
|
||||
- The role's scope may hinge on a licensing decision that is not yours to make
|
||||
- **Interview question worth asking:** "Is Trialpath a product, an internal tool, or
|
||||
undecided — and who decides?" The answer defines the job
|
||||
|
||||
### 11. Sources and Confidence
|
||||
- Company site, funding announcements, trial registry, job postings, conference agenda
|
||||
— all public, all dated
|
||||
- **Confidence: Medium-High** on structure and signals; **Low** on strategic intent,
|
||||
which is inferred from hiring language rather than stated anywhere
|
||||
- **Thin:** no public information on Trialpath's current scale or internal satisfaction
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What this example teaches that the SaaS one can't
|
||||
|
||||
- **Zero revenue is a finding, not a red flag.** Reading a clinical-stage biotech through a SaaS
|
||||
lens produces "pre-revenue, high risk" and stops. The useful read is that capital allocation, not
|
||||
revenue, is the tension every internal product lives inside.
|
||||
- **Job postings did the heaviest lifting.** "Multi-tenant" and "validation documentation" in
|
||||
postings for an *internal* tool is the strongest available signal that productization is real. No
|
||||
press release said it.
|
||||
- **Three weak signals converging beat one strong claim.** The hire, the posting language, and the
|
||||
conference focus each mean little alone. Section 9 states the convergence explicitly and labels it
|
||||
Inference.
|
||||
- **Section 10 produced an interview question, not a summary.** "Is Trialpath a product, an internal
|
||||
tool, or undecided — and who decides?" is the question the whole brief exists to surface.
|
||||
- **The confidence section admits what it doesn't know.** Low confidence on strategic intent, and
|
||||
"thin" on platform scale. A brief that claims uniform confidence across eleven sections hasn't
|
||||
been read critically by its own author.
|
||||
@@ -0,0 +1,135 @@
|
||||
# Executive Onboarding Example — Life Sciences
|
||||
|
||||
The `sample.md` example follows a VP Product into a SaaS company. This one follows the same
|
||||
playbook into **Brightwater Biologics**, a clinical-stage biotech whose product team builds
|
||||
Trialpath, the platform its trial sites and monitors run on.
|
||||
|
||||
**Why the org shape changes the onboarding:** the product organization is not the company's main
|
||||
event. The therapy program is. A product leader here has to establish what product work is *for*
|
||||
before establishing how it should run — and the answer determines whether the role is real.
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Marcus was hired as VP Product at Brightwater after eight years in enterprise SaaS. ~180 employees,
|
||||
roughly a quarter in clinical operations, no approved product, no product revenue. He inherits a
|
||||
team of four PMs and a platform two CRO partners have asked to license.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 (Before Day 1): Pre-Entry Checks
|
||||
|
||||
**Inputs gathered before accepting**
|
||||
|
||||
The five questions, and what the CEO's answers revealed:
|
||||
|
||||
- *First 90 days / first year?* — "Get Trialpath ready to sell." **Specific, and alarming.** Nobody
|
||||
had assessed whether it could be sold.
|
||||
- *All-stars?* — Named two PMs, both described in terms of responsiveness to clinical operations
|
||||
rather than product outcomes. **Signal about what the org currently rewards.**
|
||||
- *Gaps?* — "The team is reactive." Marcus noted this as a hypothesis to test, not a finding —
|
||||
reactive teams are usually a structural symptom.
|
||||
- *Constraints?* — Engineering capacity is shared with the trial data pipeline. **The real
|
||||
constraint, stated plainly and early.**
|
||||
- *Success at one year?* — "Three external customers on Trialpath."
|
||||
|
||||
**Risk signals identified**
|
||||
|
||||
- Success defined as an outcome (three customers) that depends on a regulatory gate nobody had
|
||||
assessed — vendor-grade validation documentation
|
||||
- Shared engineering with the trial program means every product decision is a capital allocation
|
||||
decision against the company's actual mission
|
||||
- No product leadership predecessor; the function was run out of clinical operations
|
||||
|
||||
**Decision**
|
||||
|
||||
Accepted — with one negotiated change: the one-year goal was restated as *"a validated,
|
||||
sellable platform with a demonstrated pilot,"* not three signed customers. Marcus's reasoning:
|
||||
he could commit to the work, not to a sales outcome gated by an unassessed regulatory question.
|
||||
|
||||
**Why this matters:** taking the original goal would have meant owning a number whose feasibility
|
||||
nobody had established. The negotiation *was* the diligence.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 (Month 1): Diagnose
|
||||
|
||||
**Actions**
|
||||
|
||||
- 30-minute conversations with four PMs, the clinical ops director, the head of engineering, the
|
||||
CFO, and — critically — two study coordinators at partner sites who use Trialpath daily
|
||||
- Included site coordinators deliberately: they're the users, they don't work for Brightwater, and
|
||||
no previous product leader had spoken to them
|
||||
|
||||
**Pattern signals (3+ independent sources)**
|
||||
|
||||
- Trialpath's roadmap is set by whichever clinical operations request is loudest that month
|
||||
- "Validation documentation" surfaced in every engineering conversation and none of the leadership
|
||||
ones
|
||||
- Coordinators at both sites had built spreadsheet workarounds for the same workflow
|
||||
|
||||
**Single-source, held loosely**
|
||||
|
||||
- One PM's assertion that the CRO partners "will definitely sign." Incentive noted: he had sourced
|
||||
the conversations.
|
||||
|
||||
**Things he wanted to fix and did not**
|
||||
|
||||
| What | Why it looks broken | What he didn't yet know |
|
||||
|---|---|---|
|
||||
| No roadmap process | Requests go straight to backlog | Whether that's dysfunction or a rational response to a trial program that genuinely reprioritizes |
|
||||
| Team labeled "reactive" | Matches the CEO's account | Whether the structure permits anything else |
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 (Month 2): Validate
|
||||
|
||||
- **Hypothesis: the team is reactive by disposition.** *Broke.* The PMs had twice attempted
|
||||
quarterly planning; both times a trial timeline change invalidated it within weeks. **They're
|
||||
responding rationally to genuine volatility.** The CEO's diagnosis was wrong, and Marcus now had
|
||||
evidence rather than an opinion.
|
||||
- **Hypothesis: validation documentation is a compliance task.** *Broke.* Regulatory confirmed it's
|
||||
a prerequisite for selling to anyone, and no one had scoped it. **This is the gate on the CEO's
|
||||
entire one-year goal.**
|
||||
- **Unwritten strategy:** the company optimizes for the trial program, correctly. Product's real job
|
||||
is to make trials run better; licensing is a possibility, not a mandate. Nobody had said this out
|
||||
loud, and the stated goal implied the opposite.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 (Month 3): Act with Evidence
|
||||
|
||||
**Shared assessment (to CEO and team):**
|
||||
|
||||
- The team is not reactive by disposition — it's structurally unable to hold a quarterly plan
|
||||
against trial volatility. Fixing it means changing the planning cadence, not the people
|
||||
- Vendor-grade validation is the gate on external licensing, unscoped, and estimated at two
|
||||
engineer-quarters
|
||||
- Recommendation: **treat licensing as a funded pilot with a kill criterion, not a commitment.**
|
||||
Assess validation first; decide after
|
||||
|
||||
**Changes underway (three, not twenty):**
|
||||
1. Six-week planning cycles instead of quarterly, matching the volatility the team actually faces
|
||||
2. Validation scoping as the first funded workstream
|
||||
3. Standing monthly contact with two site coordinators — the users nobody was talking to
|
||||
|
||||
**People:** the PM described as an all-star was strong at clinical-ops responsiveness and had never
|
||||
been asked for product judgment. Given the validation workstream as a stretch assignment.
|
||||
|
||||
---
|
||||
|
||||
## What this example teaches that the SaaS one can't
|
||||
|
||||
- **The Phase 0 negotiation was the highest-leverage act of the whole onboarding.** Restating the
|
||||
one-year goal from a sales outcome to a delivery outcome prevented owning a number gated by an
|
||||
unassessed regulatory question. That happened before day one.
|
||||
- **The CEO's people diagnosis was wrong, and evidence — not diplomacy — resolved it.** "Reactive"
|
||||
was structural. Acting on the CEO's framing in Month 1 would have targeted the wrong problem and
|
||||
probably the wrong people.
|
||||
- **The product org isn't the main event, and pretending otherwise fails.** Product's real job is to
|
||||
make trials run better. Naming the unwritten strategy out loud reframed licensing from mandate to
|
||||
option.
|
||||
- **The users didn't work for the company.** Site coordinators had never been interviewed by a
|
||||
product leader. In SaaS your users are a support ticket away; here reaching them is a deliberate
|
||||
act that has to be built into the cadence.
|
||||
@@ -0,0 +1,112 @@
|
||||
# Jobs-to-be-Done Examples — Industrial
|
||||
|
||||
JTBD analysis from **Northfield Automation**, whose retrofit control systems keep aging production
|
||||
lines running.
|
||||
|
||||
**The industrial twist:** the person doing the job and the person paying for it are different
|
||||
people with different jobs. Analyze the wrong one and you build a product that demos well and gets
|
||||
worked around on the floor.
|
||||
|
||||
---
|
||||
|
||||
## Example 1: Retrofit Control Platform (Good JTBD Analysis)
|
||||
|
||||
### The job performer: maintenance technician
|
||||
|
||||
**Functional Jobs:**
|
||||
- Get a stopped line running again without making the fault worse
|
||||
- Determine whether the fault is the controller, a sensor, the wiring, or the machine
|
||||
- Replace the failed part without re-commissioning everything around it
|
||||
- Finish the shift without a callback
|
||||
|
||||
**Emotional Jobs:**
|
||||
- Feel competent rather than made to look slow by the tool
|
||||
- Avoid the exposure of calling the OEM, which reads as "I couldn't fix it"
|
||||
- Trust the equipment enough to sleep after a night shift
|
||||
|
||||
**Social Jobs:**
|
||||
- Be the person on the crew who can fix anything
|
||||
- Give the shift supervisor an honest answer to "how long?"
|
||||
- Pass knowledge to the next tech the way it was passed to them
|
||||
|
||||
### The job performer: plant operations manager
|
||||
|
||||
**Functional Jobs:**
|
||||
- Commit to delivery dates the plant can actually hit
|
||||
- Decide whether to fund a controls refresh or defer it another year
|
||||
- Attribute downtime to a cause specific enough to act on
|
||||
|
||||
**Emotional Jobs:**
|
||||
- Feel confident defending a capital request with something better than anecdotes
|
||||
- Stop feeling at the mercy of vendors who all claim the same fix
|
||||
|
||||
**Social Jobs:**
|
||||
- Be seen by the plant manager as someone whose numbers hold up
|
||||
- Not be the person who approved the upgrade that made things worse
|
||||
|
||||
---
|
||||
|
||||
### Pains
|
||||
|
||||
**Technician:**
|
||||
- One fault light meaning seventeen things
|
||||
- Diagnostics requiring software on a laptop that can't come to the panel
|
||||
- Guessing wrong and losing two hours re-commissioning
|
||||
- Being blamed for downtime they diagnosed correctly and fast
|
||||
|
||||
**Operations manager:**
|
||||
- Downtime logged as duration and line number, with no cause
|
||||
- Vendor claims that can't be verified before purchase
|
||||
- Capital requests judged against anecdote
|
||||
|
||||
### Gains
|
||||
|
||||
**Technician:**
|
||||
- Knowing which part failed before touching anything
|
||||
- Swapping one module instead of a controller
|
||||
- Not being phoned at 2am for the same fault twice
|
||||
|
||||
**Operations manager:**
|
||||
- Downtime attributable to a cause, in a report
|
||||
- A refresh decision defensible with plant data
|
||||
|
||||
---
|
||||
|
||||
## Why this analysis works
|
||||
|
||||
- **Two performers, analyzed separately.** They share a product and share almost no jobs. Merging
|
||||
them produces "our customer wants reliability," which guides nothing.
|
||||
- **The emotional jobs are the honest ones.** "Avoid the exposure of calling the OEM" explains
|
||||
behavior that functional analysis can't — why a tech spends 40 minutes with a meter rather than
|
||||
20 seconds on the phone.
|
||||
- **The social job predicts adoption.** "Be the person who can fix anything" means a tool that makes
|
||||
the tech look replaceable will be resisted no matter how well it performs. Position it as
|
||||
amplifying expertise, not substituting for it.
|
||||
- **The manager's job explains the sale.** Downtime attribution isn't a technician feature at all —
|
||||
it's what turns a floor-level improvement into a funded purchase.
|
||||
|
||||
---
|
||||
|
||||
## Example 2: Bad JTBD Analysis (same product)
|
||||
|
||||
**Functional Jobs:**
|
||||
- Reduce downtime
|
||||
- Improve efficiency
|
||||
- Increase productivity
|
||||
|
||||
**Emotional Jobs:**
|
||||
- Feel confident in their equipment
|
||||
|
||||
**Social Jobs:**
|
||||
- Be seen as a modern operation
|
||||
|
||||
**What breaks:**
|
||||
- **"Reduce downtime" is an outcome, not a job.** Nobody wakes up hiring a product to reduce
|
||||
downtime — they hire it to *find out which module failed* so the line restarts. The job is the
|
||||
work being done; downtime is what improves if you do it well.
|
||||
- **No performer named.** These could belong to the tech, the manager, the integrator, or the
|
||||
plant manager. Since they belong to no one specific, they generate no design constraint.
|
||||
- **"Feel confident in their equipment"** is a greeting card. Compare to "avoid the exposure of
|
||||
calling the OEM," which tells you something you could build for.
|
||||
- **It fits any industrial product ever sold**, which is the reliable signal that a JTBD analysis
|
||||
has said nothing.
|
||||
@@ -0,0 +1,96 @@
|
||||
# PESTEL Analysis Example — Life Sciences
|
||||
|
||||
**Brightwater Biologics** runs multi-site clinical trials and builds **Trialpath**, the platform its
|
||||
coordinators, monitors, and CRO partners use.
|
||||
|
||||
**Why this domain changes PESTEL:** in most markets, Legal and Political are background conditions.
|
||||
Here they are the *product constraints* — they determine what can ship, to whom, and after what
|
||||
documentation. A PESTEL that treats regulation as context rather than as design input has missed
|
||||
the point.
|
||||
|
||||
---
|
||||
|
||||
```markdown
|
||||
## PESTEL Analysis: Trialpath — Clinical Trial Operations Platform
|
||||
|
||||
### Political
|
||||
- Public funding priorities for clinical research shift with administrations, moving trial
|
||||
volume between therapeutic areas on a multi-year lag
|
||||
- Cross-border data movement between trial sites is increasingly politically contested,
|
||||
independent of the legal frameworks that formalize it
|
||||
- **So what:** trial volume by therapeutic area is not something we forecast well. Platform
|
||||
design should be therapeutic-area agnostic, and we should resist optimizing for the mix
|
||||
we happen to serve today
|
||||
|
||||
### Economic
|
||||
- Small-sponsor funding is rate-sensitive; a tightening cycle thins the segment we identified
|
||||
as our best fit
|
||||
- Site staffing costs rise faster than trial budgets, pushing sponsors toward
|
||||
coordinator-efficiency tools
|
||||
- CRO consolidation concentrates buying power in fewer, larger organizations
|
||||
- **So what:** our target segment shrinks in exactly the conditions that make our value
|
||||
proposition strongest. Plan for a smaller, more motivated market rather than a growing one
|
||||
|
||||
### Social
|
||||
- Coordinator turnover at sites runs high, so institutional knowledge leaves regularly
|
||||
- Patient expectations around participation convenience are rising, pushing decentralized
|
||||
and hybrid trial designs
|
||||
- Trust in clinical research varies sharply by community, affecting recruitment
|
||||
- **So what:** high turnover makes "learnable in a day" a durable requirement, not a nice-to-have.
|
||||
Any design that assumes an experienced coordinator degrades within a year
|
||||
|
||||
### Technological
|
||||
- Electronic data capture is table stakes; differentiation has moved to workflow and integration
|
||||
- AI-assisted document review is maturing, with unresolved questions about its acceptability
|
||||
in regulated submissions
|
||||
- Decentralized trial tooling is fragmenting into many point solutions
|
||||
- **So what:** the AI opportunity is real and the acceptability question is unanswered. Build
|
||||
where AI assists a human who remains accountable; avoid anything that would need to be
|
||||
defended as an autonomous decision in a submission
|
||||
|
||||
### Environmental
|
||||
- Site travel for monitoring visits is a growing reporting concern for large sponsors
|
||||
- Sustainability reporting is entering vendor selection for enterprise buyers
|
||||
- **So what:** remote monitoring capability has a second, non-obvious buyer rationale.
|
||||
Low priority for our current segment, rising for the segment above it
|
||||
|
||||
### Legal
|
||||
- Regulatory expectations for computerized systems in trials require validation
|
||||
documentation from the vendor, not just the user
|
||||
- Data protection regimes differ by jurisdiction and by trial, and both apply simultaneously
|
||||
- Audit trail requirements are non-negotiable and shape data model decisions
|
||||
- **So what:** **this is the gating category.** Vendor-grade validation documentation is the
|
||||
entry ticket to selling at all — it is not a compliance task that follows a product decision,
|
||||
it IS the product decision. Audit trail requirements constrain the data model before a
|
||||
single feature is designed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Assumptions this analysis exposed
|
||||
|
||||
- **We assumed our best segment was growing.** Economic analysis says it thins under exactly the
|
||||
conditions that make us most valuable. That reframes the opportunity from "growth market" to
|
||||
"small motivated market" — which changes what a sensible investment looks like.
|
||||
- **We assumed AI document review was a roadmap question.** It's an acceptability question first,
|
||||
and nobody has answered it. Building AI that assists an accountable human is safe; building AI
|
||||
that decides is a bet on a regulatory position that doesn't exist yet.
|
||||
- **We assumed validation documentation was a compliance workstream.** It's the gate. This single
|
||||
finding reordered the roadmap.
|
||||
|
||||
---
|
||||
|
||||
## Why Legal carries the analysis here
|
||||
|
||||
In most PESTEL work, Legal is a paragraph acknowledging that laws exist. Here it produced the
|
||||
constraint that determined the product's sequencing, its data model, and whether the business is
|
||||
viable at all.
|
||||
|
||||
**The tell that you've done this right in a regulated domain:** at least one "so what" should
|
||||
change something already on your roadmap. If every conclusion is "keep monitoring," you've written
|
||||
a description of the industry rather than an analysis of your position in it.
|
||||
|
||||
**The trap on the other side:** treating every regulation as a blocker. Environmental here is
|
||||
honestly low-priority for the current segment, and saying so is more useful than manufacturing
|
||||
urgency to make the section feel complete. A PESTEL where all six categories are equally critical
|
||||
is a PESTEL that hasn't prioritized.
|
||||
@@ -0,0 +1,96 @@
|
||||
# PoL Probe Examples — Industrial
|
||||
|
||||
Proof-of-Life probes from **Northfield Automation** during NFA-500 development.
|
||||
|
||||
**The industrial twist:** you can't ship a fake door to a plant floor. There's no feature flag, no
|
||||
5% rollout, no "we'll revert if it goes badly." That makes cheap physical probes *more* valuable —
|
||||
because the real experiment costs a tooling cycle and takes a year.
|
||||
|
||||
---
|
||||
|
||||
## ✅ Good: Task-Focused PoL Probe
|
||||
|
||||
**Hypothesis:** "A technician can identify which I/O slot faulted from the front panel in under 30
|
||||
seconds, wearing work gloves, in plant lighting."
|
||||
|
||||
**Probe:** A printed card mounted at panel height showing the proposed front-panel layout. Nine
|
||||
technicians at three sites were given a simulated fault ("slot 4 has failed — show me how you'd
|
||||
know") and timed.
|
||||
|
||||
**Cost:** Two days, a color printer, and site visits already scheduled for other work.
|
||||
|
||||
**What we learned:**
|
||||
- 7 of 9 identified the slot in under 20 seconds. Two took over a minute — both at the site with
|
||||
the dimmest panel lighting
|
||||
- All nine reached for the card with a gloved hand and none attempted a precise touch
|
||||
- Four asked "does it tell me *what* failed or just *where*?" — a question nobody on the team had
|
||||
thought to answer
|
||||
|
||||
**What changed:** The touchscreen concept was dropped. Indicator height increased for low-light
|
||||
legibility. A fault-type code was added beside the slot number, from a question we hadn't known to
|
||||
ask.
|
||||
|
||||
**Why this is a good probe:**
|
||||
- **It tested the riskiest assumption** — legibility under real conditions — not the easiest one
|
||||
- **It cost nothing and could fail cheaply.** Two of nine failing was a finding, not a setback
|
||||
- **It ran where the work happens.** The same card tested in an office would have passed easily and
|
||||
taught nothing
|
||||
- **It surfaced an unknown unknown.** The "what failed, not just where" question came from putting a
|
||||
real artifact in front of a real user
|
||||
|
||||
---
|
||||
|
||||
## ✅ Good: Feasibility PoL Probe
|
||||
|
||||
**Hypothesis:** "Module failures show a detectable precursor signal in I/O data before they fail."
|
||||
|
||||
**Probe:** Pulled signal logs preceding 50 known module failures from the service database. One
|
||||
engineer, one week, no new code.
|
||||
|
||||
**What we learned:** Precursor patterns appeared in **9 of 50**.
|
||||
|
||||
**What changed:** The predictive-maintenance epic was killed after three weeks and roughly zero
|
||||
engineering cost.
|
||||
|
||||
**Why this is a good probe:** it used data that already existed to answer a question that would
|
||||
otherwise have consumed two quarters. In a domain where a false "your line is about to stop" alert
|
||||
destroys trust faster than no alert at all, being wrong 80% of the time was disqualifying — and the
|
||||
probe found that out before anyone wrote firmware.
|
||||
|
||||
---
|
||||
|
||||
## ❌ Bad: The Probe That Couldn't Fail
|
||||
|
||||
**Hypothesis:** "Customers want better diagnostics."
|
||||
|
||||
**Probe:** Showed twelve customers a slide deck of the proposed NFA-500 diagnostics and asked
|
||||
whether they'd find it valuable.
|
||||
|
||||
**Result:** Twelve of twelve said yes.
|
||||
|
||||
**Why this is a bad probe:**
|
||||
- **Nobody says no to "would you like a better version of a thing you complain about."** The result
|
||||
was determined before the probe ran
|
||||
- **It tested enthusiasm, not behavior.** A tech saying "that'd be great" in a conference room tells
|
||||
you nothing about whether they can read it at panel height with gloves on
|
||||
- **It had no failure condition.** A probe that cannot come back negative isn't a probe, it's a
|
||||
presentation
|
||||
- **It confirmed a decision already made**, which is the most expensive form of research — it buys
|
||||
false confidence at the price of real learning
|
||||
|
||||
**The fix:** the printed-card probe above. Same question, four days, and two of nine failed — which
|
||||
is exactly what made it worth running.
|
||||
|
||||
---
|
||||
|
||||
## What hardware changes about probing
|
||||
|
||||
| | Software | Hardware / industrial |
|
||||
|---|---|---|
|
||||
| Cheapest real test | Ship to 5% and measure | Paper, cardboard, or existing data |
|
||||
| Failure cost | Revert the flag | Tooling cycle, possibly a year |
|
||||
| Where to test | Wherever users are | **Where the work physically happens** |
|
||||
| Riskiest assumption | Usually demand | Often physical: legibility, reach, environment |
|
||||
|
||||
The discipline is identical; the artifacts are cheaper and more physical, and the site visit is
|
||||
non-negotiable. A probe run in an office tests an office.
|
||||
@@ -0,0 +1,105 @@
|
||||
# Example: Diagnose a Metric Drop
|
||||
|
||||
**Prompt:** "Weekly active users dropped 8% last week. What do you do?"
|
||||
|
||||
## Why this example exists
|
||||
|
||||
The `improve-youtube.md` example covers an **improvement** question, where the work is
|
||||
segmentation and opportunity selection. This is a **diagnostic** question, and it rewards a
|
||||
different shape entirely.
|
||||
|
||||
Candidates who pattern-match a diagnostic prompt onto the improvement framework — segment users,
|
||||
list pain points, propose features — fail it, because the interviewer isn't asking what to build.
|
||||
They're asking whether you can tell a real problem from an artifact before you spend a team's
|
||||
quarter on it.
|
||||
|
||||
**The structural difference:** an improvement question opens outward toward opportunity. A
|
||||
diagnostic question narrows inward toward cause. Solutions are the last thing you reach for, and
|
||||
often you shouldn't reach for them at all.
|
||||
|
||||
---
|
||||
|
||||
## Condensed Walkthrough
|
||||
|
||||
### 1. Clarify — establish the metric is real before explaining it
|
||||
|
||||
"Before I theorize, four quick questions:
|
||||
|
||||
1. **Is the measurement trustworthy?** Any logging changes, SDK releases, or analytics
|
||||
migrations that week?
|
||||
2. **What's the comparison?** Down 8% versus the prior week, the same week last year, or trend?
|
||||
3. **How is WAU defined here**, and did the definition change?
|
||||
4. **Is the drop uniform** or concentrated in a platform, geography, or cohort?"
|
||||
|
||||
**Why this comes first:** a meaningful share of real-world metric drops are instrumentation
|
||||
changes, holiday effects, or definitional shifts. Explaining an artifact with a product theory is
|
||||
the single most common way to fail this question — and in the real job, the most expensive.
|
||||
|
||||
*Assume for this answer: instrumentation is clean, it's an 8% week-over-week drop against a flat
|
||||
trend, and it's concentrated in Android users in one region.*
|
||||
|
||||
### 2. Narrow before hypothesizing
|
||||
|
||||
That concentration eliminates most global explanations immediately.
|
||||
|
||||
Still live:
|
||||
- An Android release regression
|
||||
- A regional outage, carrier, or network issue
|
||||
- A regional competitor or pricing move
|
||||
- A local event — holiday, disruption, seasonality
|
||||
- An app store or distribution change in that market
|
||||
|
||||
Ruled out by the concentration itself: pricing changes elsewhere, global algorithm changes,
|
||||
company-wide seasonality.
|
||||
|
||||
**The discipline:** the shape of the drop does more elimination work than any hypothesis list. Get
|
||||
the shape first.
|
||||
|
||||
### 3. Order hypotheses by cheapness to test, not by likelihood
|
||||
|
||||
| Hypothesis | How to test | Time |
|
||||
|---|---|---|
|
||||
| Android release regression | Compare app versions; check crash rate by version | Minutes |
|
||||
| Regional outage | Check error rates and CDN status for the region | Minutes |
|
||||
| App store / distribution change | Check install and update rates | Hours |
|
||||
| Competitor or pricing move | Market check, app store rankings | A day |
|
||||
| Local event | Calendar, news for the region | A day |
|
||||
|
||||
"I'd start with the top two because they're minutes of work, not because they're most likely.
|
||||
Cheap tests first is how you avoid spending a week on the interesting hypothesis."
|
||||
|
||||
### 4. Reason to a conclusion
|
||||
|
||||
*Assume: crash rate on Android 4.2.1, released that week, is 6x baseline in that region only, and
|
||||
the region's dominant device family maps to a specific OS version.*
|
||||
|
||||
"That's the cause: a release regression, device-specific, which is why it looked regional. The
|
||||
fix is a rollback or patch, and the follow-up is why device coverage in that market wasn't in the
|
||||
release test matrix."
|
||||
|
||||
### 5. Say what you'd do about the process, not just the bug
|
||||
|
||||
- **Immediate:** roll back 4.2.1 for affected devices; confirm recovery
|
||||
- **Short-term:** add that device family to pre-release testing
|
||||
- **Systemic:** alert on crash rate *by version and region*, not aggregate — the aggregate never
|
||||
moved enough to page anyone
|
||||
|
||||
**This is the part that separates answers.** The bug is a day's work. The missing alert is why an
|
||||
8% drop took a week to notice, and it will cause the next one too.
|
||||
|
||||
---
|
||||
|
||||
## What to notice
|
||||
|
||||
- **No feature was proposed.** The prompt sounded like a product question and was an engineering
|
||||
regression. Reaching for the improvement framework would have produced a confident, irrelevant
|
||||
answer.
|
||||
- **Clarifying questions did real work.** "Is it uniform or concentrated?" eliminated more
|
||||
hypotheses than any subsequent reasoning step.
|
||||
- **Hypotheses were ordered by test cost, not plausibility.** This is the habit interviewers are
|
||||
actually probing — it's what makes someone fast in the job rather than merely insightful.
|
||||
- **The answer ended on the detection gap.** Aggregate alerting missed a concentrated failure.
|
||||
Naming the systemic fix shows you think past the incident.
|
||||
- **It stayed a diagnosis throughout.** Compare with `improve-youtube.md`, which is right to spend
|
||||
most of its length on segmentation and opportunity. Same interviewer, same hour, opposite shape —
|
||||
and using the wrong one is the failure mode this pair exists to teach.
|
||||
@@ -0,0 +1,82 @@
|
||||
# Recommendation Canvas Example — Life Sciences
|
||||
|
||||
An AI investment decision at **Brightwater Biologics** for **Trialpath**, the platform its
|
||||
coordinators and monitors use to run clinical studies.
|
||||
|
||||
**Why this domain changes the AI decision:** the question isn't only "does the model work well
|
||||
enough." It's "who is accountable when it's wrong, and can that answer survive an audit." A model
|
||||
at 94% accuracy is excellent in most products and potentially unusable here, depending entirely on
|
||||
what happens with the other 6%.
|
||||
|
||||
---
|
||||
|
||||
```markdown
|
||||
## AI Query Triage Canvas — Trialpath
|
||||
|
||||
### The Opportunity
|
||||
Monitors raise data queries against site-entered trial data. Sites currently receive them as an
|
||||
undifferentiated queue and work them in arrival order. Median resolution is 11 days; the queries
|
||||
that actually block database lock are indistinguishable from routine ones until someone reads
|
||||
each one.
|
||||
|
||||
### Target Outcome
|
||||
Reduce median resolution time for lock-blocking queries from 11 days to under 4, without
|
||||
increasing the rate of queries closed incorrectly.
|
||||
|
||||
### Hypotheses
|
||||
1. **If** queries are ranked by likely impact on database lock, **then** sites will resolve
|
||||
blocking queries first, **because** the current queue gives them no basis to choose
|
||||
2. **If** ranking is presented as a suggestion with the reason shown, **then** coordinators will
|
||||
use it, **because** an unexplained ordering in a regulated workflow gets ignored
|
||||
3. **If** a human remains the decision-maker on every query, **then** the capability stays within
|
||||
existing validation scope
|
||||
|
||||
### AI Suitability
|
||||
- **Good fit:** ranking and suggestion over a corpus of historical queries with known outcomes
|
||||
- **Poor fit:** auto-closing queries, auto-editing data, or anything that writes to the
|
||||
trial record without a person
|
||||
- **The line:** the model orders work. A human does the work and is accountable for it.
|
||||
|
||||
### Risks
|
||||
| Risk | Severity | Mitigation |
|
||||
|---|---|---|
|
||||
| Model deprioritizes a blocking query | **High** | Ranking never hides queries; full queue always visible and sortable |
|
||||
| Coordinators over-trust the ranking | Medium | Show the reason for each rank; no confidence scores presented as certainty |
|
||||
| Regulatory acceptability of AI in workflow | **High** | Suggestion-only, human-in-loop, decisions and rationale in the audit trail |
|
||||
| Training data reflects historical bias | Medium | Validate ranking against a held-out set from sites not in training data |
|
||||
| Model drift as protocols change | Medium | Quarterly re-evaluation; documented retraining trigger |
|
||||
|
||||
### Positioning
|
||||
Not "AI-powered trial management." Internally and externally: *"Trialpath suggests which queries
|
||||
to work first, and shows you why."* The claim is deliberately small and defensible.
|
||||
|
||||
### Kill Criteria
|
||||
- If held-out ranking accuracy on blocking queries falls below 80%, stop
|
||||
- If validation scope must expand to a full computerized-system revalidation, stop and reassess
|
||||
cost against the 7-day benefit
|
||||
- If coordinators in pilot ignore the ranking more than half the time, the problem isn't ranking
|
||||
|
||||
### Decision
|
||||
**Proceed to a two-site pilot**, suggestion-only, with the validation impact assessment completed
|
||||
before any model touches production data.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What this canvas teaches that the SaaS one can't
|
||||
|
||||
- **"AI suitability" has a hard line, and it's drawn on accountability.** The model *orders* work;
|
||||
a human *does* it. That single distinction keeps the capability inside existing validation scope
|
||||
— and if it were crossed, the entire cost structure of the feature changes.
|
||||
- **Two risks are rated High, and neither is model accuracy.** Deprioritizing a blocking query and
|
||||
regulatory acceptability both outrank raw performance. In most products accuracy is the headline
|
||||
risk; here it's a mid-tier input to a bigger question.
|
||||
- **The mitigation for the top risk is a design constraint, not a model improvement.** "Ranking
|
||||
never hides queries" means the worst case degrades to today's behavior. Designing the failure
|
||||
mode to be the status quo is often stronger than making the model better.
|
||||
- **Positioning is deliberately unimpressive.** "Suggests which queries to work first, and shows
|
||||
you why" is a smaller claim than the marketing instinct wants — and it's the version that
|
||||
survives an auditor asking what the system does.
|
||||
- **A kill criterion targets the mechanism, not just the metric.** If coordinators ignore the
|
||||
ranking, the problem isn't ranking quality — it's that ordering wasn't the constraint. That
|
||||
criterion prevents a year of model tuning against the wrong bottleneck.
|
||||
@@ -0,0 +1,115 @@
|
||||
# Skill Authoring Example
|
||||
|
||||
A real build from this repository: `lifecycle-play-advisor`, the Interactive skill that diagnoses
|
||||
whether a fading product should be extended, replaced, or retired.
|
||||
|
||||
**Why this one:** it shows the Preflight phase doing the work it exists to do — nearly stopping the
|
||||
build — and it shows the Component + Interactive pairing decision that this repo prefers over one
|
||||
large skill.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Preflight
|
||||
|
||||
```bash
|
||||
./scripts/find-a-skill.sh --mode trigger "product lifecycle decline extend replace"
|
||||
# -> No matching skills found
|
||||
```
|
||||
|
||||
Then a wider check, because "no matches" often means the query was wrong rather than the gap real:
|
||||
|
||||
```bash
|
||||
grep -rl "Product Life Cycle\|product lifecycle\|PLC" skills/*/SKILL.md
|
||||
# -> company-intel, eol-readiness-advisor, eol-process (references only, no PLC skill)
|
||||
```
|
||||
|
||||
**Overlap found:** `organic-growth-advisor` and `ansoff-matrix` both cover growth options.
|
||||
|
||||
**Why not extend one of those?** They ask *where does growth come from.* This asks *what do we do
|
||||
with this specific product at the decline inflection.* Different question, different entry point,
|
||||
different user state. The honest boundary: when the answer here is "extend," it hands off to
|
||||
`organic-growth-advisor` for which growth path the variant serves.
|
||||
|
||||
**Type decision:** the source material contained both a framework (PLC grid, three plays, seven
|
||||
replacement hazards, a risk register) and a diagnostic flow. That's the classic signal for the
|
||||
repo's preferred pairing:
|
||||
|
||||
- `product-lifecycle-plays` — **Component**, the reusable framework
|
||||
- `lifecycle-play-advisor` — **Interactive**, the guided triage
|
||||
|
||||
**Rejected alternative:** one large skill holding both. It would have buried the framework inside a
|
||||
conversation flow, making it unusable as reference for someone who just wants the hazard list.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Generate draft
|
||||
|
||||
Written by hand. The source was workshop material with a strong internal structure already, so
|
||||
`add-a-skill.sh` would have flattened it. **Rule of thumb:** use the generator when source material
|
||||
is unstructured, write by hand when the structure is the value.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Tighten
|
||||
|
||||
What the review pass changed:
|
||||
|
||||
- **Added a "when NOT to use."** The first draft only said when to use it, which meant it read as
|
||||
applicable to every product question.
|
||||
- **Added "nothing yet" as a real outcome.** The draft always produced a play. A mature product
|
||||
throwing off margin doesn't need a project, and a skill that always recommends action is a skill
|
||||
that generates busywork.
|
||||
- **Made the extension test mandatory rather than optional.** Extension is the cheapest play and the
|
||||
most frequently skipped; leaving the test optional guaranteed it would be skipped.
|
||||
- **Added two conversation-flow examples** (Interactive skills substitute these for the usual
|
||||
worked artifacts) — one where the recommendation contradicts the user's stated plan, because a
|
||||
triage skill that only confirms is worthless.
|
||||
- **Cut a "Benefits of Lifecycle Thinking" section.** Pure filler. Nothing under it changed a
|
||||
decision.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Validate
|
||||
|
||||
```bash
|
||||
bash scripts/test-a-skill.sh --smoke skills/lifecycle-play-advisor/SKILL.md
|
||||
# PASS conformance
|
||||
# PASS linked skill paths
|
||||
# PASS smoke checks
|
||||
|
||||
python3 scripts/check-skill-triggers.py
|
||||
# All skills pass trigger-readiness checks.
|
||||
```
|
||||
|
||||
**A real failure caught here on the sibling workflow skill:** `eol-process` failed smoke with
|
||||
*"section 'Application' is empty."* Cause: an H2 phase header (`## Phase 1: Decide`) directly
|
||||
following `## Application`, so the parser saw no content between them. Fix: a lead-in paragraph,
|
||||
the same way `discovery-process` does it.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Integrate
|
||||
|
||||
- README: new "Aging products" nav block, plus the pack table row
|
||||
- `marketplace.json`: entries added by hand, alphabetically — **nothing automates this**, and
|
||||
`check-library-drift.py` is what catches you forgetting
|
||||
- Cross-references added in both directions with `eol-readiness-advisor`,
|
||||
`organic-growth-advisor`, and `ansoff-matrix`
|
||||
- `generate-catalog.py`, then `build-dist.sh`, then `check-dist-freshness.py`
|
||||
- `validate-skills.sh` — 77 skills, no drift
|
||||
|
||||
---
|
||||
|
||||
## What to notice
|
||||
|
||||
- **Preflight nearly killed the build, and that's the point.** Two existing growth skills looked
|
||||
like overlap. Articulating the boundary — *where does growth come from* versus *what do we do with
|
||||
this product* — is what justified a new skill and produced the cross-references.
|
||||
- **The pairing decision came from the source material's shape**, not from preference. Framework
|
||||
plus flow means Component plus Interactive.
|
||||
- **Tightening removed a section and added a non-answer.** "Nothing yet" as a valid outcome is worth
|
||||
more than most features, because it stops the skill from manufacturing work.
|
||||
- **The validator caught a structural bug no human review would have.** An empty-looking Application
|
||||
section is invisible when you're reading the file top to bottom.
|
||||
- **Integration is the phase people skip.** Marketplace, catalog, and dist are all hand-triggered.
|
||||
A skill that exists in `skills/` but nowhere else is a skill nobody will find.
|
||||
@@ -0,0 +1,126 @@
|
||||
# Skill Authoring Worksheet
|
||||
|
||||
A per-skill tracker for the five phases, with the commands and the definition of done. Quality
|
||||
checks at the bottom.
|
||||
|
||||
## Provenance
|
||||
Dogfooded from this repo's own authoring standards — `CLAUDE.md`, `CONTRIBUTING.md`, and the
|
||||
validation scripts under `scripts/`.
|
||||
|
||||
**Note:** this is a meta-skill about building skills in this repository, so it ships one worked
|
||||
example rather than the usual two business domains. A second "domain" here would be artificial.
|
||||
|
||||
---
|
||||
|
||||
## The tracker
|
||||
|
||||
```markdown
|
||||
## Skill Build: [skill-name]
|
||||
|
||||
**Type:** [component / interactive / workflow]
|
||||
**Theme:** [existing theme, or "new — justify below"]
|
||||
**Source material:** [file, transcript, prompt, or "original"]
|
||||
|
||||
---
|
||||
|
||||
### Phase 1 — Preflight
|
||||
|
||||
- [ ] Searched for overlap: `./scripts/find-a-skill.sh --keyword "<topic>"`
|
||||
- Overlapping skills found: [list, or none]
|
||||
- **Decision:** [new skill / extend an existing one / merge]
|
||||
- **Why not extend an existing skill?** [answer — this is the question most often skipped]
|
||||
|
||||
**Type rationale:**
|
||||
- Component = one artifact or template
|
||||
- Interactive = 3-5 adaptive questions + numbered options
|
||||
- Workflow = multi-phase orchestration
|
||||
- **Chosen because:** [reason]
|
||||
|
||||
---
|
||||
|
||||
### Phase 2 — Generate draft
|
||||
|
||||
- [ ] `./scripts/add-a-skill.sh research/<file>.md` (from source material)
|
||||
- [ ] `./scripts/build-a-skill.sh` (guided prompts)
|
||||
- [ ] Written by hand
|
||||
|
||||
---
|
||||
|
||||
### Phase 3 — Tighten
|
||||
|
||||
- [ ] Clear "when to use" — and a "when NOT to use"
|
||||
- [ ] At least one concrete example; two from different business domains where the skill isn't
|
||||
definitionally single-domain
|
||||
- [ ] `template.md` if the skill produces an artifact — output schema as a copy/paste fill-in,
|
||||
with quality checks
|
||||
- [ ] At least one explicit anti-pattern, with its consequence named
|
||||
- [ ] No filler, no vague consultant-speak
|
||||
- [ ] Pedagogy intact — explanation is load-bearing, not decoration
|
||||
|
||||
---
|
||||
|
||||
### Phase 4 — Validate
|
||||
|
||||
```bash
|
||||
./scripts/test-a-skill.sh --skill <skill-name> --smoke
|
||||
python3 scripts/check-skill-metadata.py skills/<skill-name>/SKILL.md
|
||||
python3 scripts/check-skill-triggers.py
|
||||
```
|
||||
|
||||
- [ ] Conformance passes
|
||||
- [ ] Linked skill paths resolve
|
||||
- [ ] Smoke checks pass with no new warnings
|
||||
- [ ] Trigger audit clean (`description` contains a literal "Use when")
|
||||
|
||||
---
|
||||
|
||||
### Phase 5 — Integrate
|
||||
|
||||
- [ ] Added to the correct README category table and nav block
|
||||
- [ ] Added to `.claude-plugin/marketplace.json` — **hand-maintained**, alphabetical
|
||||
- [ ] Cross-referenced from related skills' References sections
|
||||
- [ ] `python3 scripts/generate-catalog.py`
|
||||
- [ ] `bash scripts/build-dist.sh`
|
||||
- [ ] `python3 scripts/check-dist-freshness.py`
|
||||
- [ ] `bash scripts/validate-skills.sh` — the CI path
|
||||
|
||||
---
|
||||
|
||||
### Frontmatter check
|
||||
|
||||
- [ ] `name` matches the folder name exactly
|
||||
- [ ] `description` ≤200 chars, contains a literal "Use when"
|
||||
- [ ] `intent`, `type` present
|
||||
- [ ] `theme`, `best_for`, `scenarios`, `estimated_time` present
|
||||
- [ ] YAML values containing colons are quoted
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality checks
|
||||
|
||||
**Preflight**
|
||||
- [ ] You genuinely searched before building. Duplicate skills are the most common waste in this repo
|
||||
- [ ] "Why not extend an existing skill?" has a real answer
|
||||
|
||||
**Anatomy**
|
||||
- [ ] Sections in order: Purpose, Input, Key Concepts, Application, Examples, Common Pitfalls,
|
||||
References
|
||||
- [ ] The Input section reads as invitation, never as a gate — "Works best with," plus reassurance
|
||||
that arriving empty-handed is fine
|
||||
- [ ] No bare `$ARGUMENTS` anywhere in the body (validation fails on it, and the stance is
|
||||
deliberate)
|
||||
|
||||
**Pedagogy — the one that matters most here**
|
||||
- [ ] Anti-patterns are present and explain the *consequence*, not just the mistake
|
||||
- [ ] Examples show reasoning, not only output
|
||||
- [ ] Nothing was cut purely to tighten copy. **Stripping learning scaffolding is a defect in this
|
||||
repo, not an improvement**
|
||||
|
||||
**Workflow skills specifically**
|
||||
- [ ] `## Application` has a lead-in paragraph before the first phase header — an H2 phase header
|
||||
immediately after it makes smoke report the section as empty
|
||||
|
||||
**Integration**
|
||||
- [ ] Marketplace entry added — nothing else adds it for you
|
||||
- [ ] Catalog and dist regenerated, freshness check passing
|
||||
@@ -0,0 +1,101 @@
|
||||
# Stakeholder Identification Example — Industrial
|
||||
|
||||
**Initiative:** Northfield Automation is adding remote firmware update to the NFA-500. A controller
|
||||
in a customer's panel can be updated from a service console hundreds of miles away.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Brainstorm (unfiltered)
|
||||
|
||||
Field service technicians · plant maintenance staff · plant operations managers · controls
|
||||
engineers at integrators · the 8 channel partners · plant IT and OT security · Northfield firmware
|
||||
engineering · Northfield service org · Regulatory (UL/CE) · Legal · insurers of customer plants ·
|
||||
plant safety officers · customers running validated processes · the tooling vendor · competitors
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Categorize
|
||||
|
||||
| Stakeholder | Ally | Audience | Influencer |
|
||||
|---|---|---|---|
|
||||
| Northfield field service | ✓ | ✓ | ✓ |
|
||||
| Plant maintenance staff | | ✓ | ✓ |
|
||||
| Plant operations managers | | ✓ | ✓ |
|
||||
| Plant OT security | | ✓ | ✓ |
|
||||
| Channel partners (8) | ✓ | ✓ | ✓ |
|
||||
| Regulatory (UL/CE) | | | ✓ |
|
||||
| Plant safety officers | | ✓ | ✓ |
|
||||
| Validated-process customers | | ✓ | ✓ |
|
||||
|
||||
**The overlap that mattered:** channel partners are all three. They benefit (fewer support
|
||||
escalations), they're affected (their service revenue includes site visits this feature removes),
|
||||
and they influence what their customers adopt. **Ally and threatened party simultaneously.**
|
||||
|
||||
---
|
||||
|
||||
## Step 3: R/P/D
|
||||
|
||||
| Stakeholder | R | P | D | Notes |
|
||||
|---|---|---|---|---|
|
||||
| Regulatory body | — | ✓ | — | Listing impact determines whether this ships at all |
|
||||
| Plant OT security | — | ✓ | — | Can refuse to open the network path, per site |
|
||||
| Plant operations manager | — | ✓ | ✓ | Decides enrollment for their plant |
|
||||
| Northfield VP Engineering | ✓ | — | ✓ | Funds and prioritizes |
|
||||
| Channel partners | — | ✓ | — | Effectively gate adoption at accounts they service |
|
||||
|
||||
**Gap found:** **plant OT security** holds P at every single site and appeared eleventh in the
|
||||
brainstorm. A remote update path is a network ingress into an operational-technology environment —
|
||||
the exact thing OT security exists to refuse. Missing them wouldn't have delayed launch; it would
|
||||
have made the feature unadoptable one site at a time, invisibly.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Equity lens
|
||||
|
||||
- **Who bears cost without power?** **Plant maintenance staff.** A controller on their line can now
|
||||
change state initiated by someone off-site. If an update goes wrong at 2am, they are the ones
|
||||
standing at the panel — and they have no say in enrollment.
|
||||
- **Whose perspective is missing because we assumed someone represents them?** We assumed the
|
||||
operations manager speaks for maintenance staff. On "who can change my equipment remotely," that's
|
||||
not a safe assumption.
|
||||
- **Third-degree affected?** Plant safety officers, who own the incident review if an update
|
||||
contributes to an unplanned stop.
|
||||
|
||||
**Added:** plant maintenance staff and safety officers, both promoted from mentions to real
|
||||
stakeholders.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Bias check
|
||||
|
||||
- **Who did we default to naming?** People inside Northfield, then the buyer. Seven of the first
|
||||
ten names were ours or the person who signs.
|
||||
- **Who was absent, and why?** OT security and safety officers — because we think of this as a
|
||||
product feature and they think of it as a change to a controlled environment.
|
||||
- **What did we assume?** That "the customer" is the operations manager. On this feature, OT
|
||||
security can veto and maintenance staff bear the consequence.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Priority targets
|
||||
|
||||
| Name | Category | R/P/D | What we need to learn |
|
||||
|---|---|---|---|
|
||||
| Plant OT security | Audience + Influencer | P | What network path, authentication, and audit evidence they'd require before permitting ingress — and whether any would refuse outright |
|
||||
| Plant maintenance staff | Audience + Influencer | — | What they need to trust a remote change: notification, veto, rollback visibility, or something else |
|
||||
| Channel partners | Ally + Influencer | P | Whether removing site visits threatens their service revenue enough to slow adoption, and what would make it a win for them |
|
||||
|
||||
---
|
||||
|
||||
## What to notice
|
||||
|
||||
- **The gap test found the true blocker.** OT security holds Permission at every site and surfaced
|
||||
eleventh. Nothing about the schedule would have flagged it; the R/P/D pass did.
|
||||
- **The equity lens found the people who absorb the risk.** Maintenance staff live with the
|
||||
consequences of a remote change and have no say in whether their plant enrolls.
|
||||
- **A stakeholder is an ally and a threatened party at once.** Channel partners benefit and lose
|
||||
revenue simultaneously. Naming both makes the third priority question honest — "what would make
|
||||
this a win for them" rather than "how do we get them on board."
|
||||
- **The bias pattern matches the SaaS example.** Both teams defaulted to builders and buyers, and
|
||||
both missed a Permission-holder who could stop the work. That's the pattern the check exists to
|
||||
surface, and it appears to be domain-independent.
|
||||
@@ -0,0 +1,96 @@
|
||||
# Stakeholder Identification Example — SaaS
|
||||
|
||||
**Initiative:** Fieldlight is adding a customer-facing arrival-window feature to Next Scheduling —
|
||||
technicians' ETAs become visible to the end customer whose home or site they're visiting.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Brainstorm (unfiltered)
|
||||
|
||||
Dispatchers · field technicians · service business owners (our buyer) · the end customer receiving
|
||||
the service · Fieldlight support · Fieldlight sales · CS · engineering · SMS/notification vendor ·
|
||||
Legal · the technicians' union at two enterprise accounts · competitors · app store reviewers ·
|
||||
insurance carriers for our customers · integrators who resell Fieldlight
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Categorize
|
||||
|
||||
| Stakeholder | Ally | Audience | Influencer |
|
||||
|---|---|---|---|
|
||||
| Service business owners (buyer) | ✓ | ✓ | ✓ |
|
||||
| Dispatchers | ✓ | ✓ | |
|
||||
| Field technicians | | ✓ | ✓ |
|
||||
| End customers | | ✓ | ✓ |
|
||||
| Fieldlight support | | ✓ | ✓ |
|
||||
| Legal | | | ✓ |
|
||||
| Technicians' union (2 accounts) | | ✓ | ✓ |
|
||||
| Notification vendor | | | ✓ |
|
||||
|
||||
**The overlap that mattered:** field technicians are an audience *and* an influencer. They don't buy
|
||||
Fieldlight, but they tell their employer what's unusable — and a tracked-location feature is exactly
|
||||
the kind of thing they escalate.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: R/P/D
|
||||
|
||||
| Stakeholder | R | P | D | Notes |
|
||||
|---|---|---|---|---|
|
||||
| Service business owner | — | ✓ | ✓ | Decides adoption per account |
|
||||
| Fieldlight CPO | ✓ | — | ✓ | Funds and prioritizes |
|
||||
| Legal | — | ✓ | — | Location-data disclosure review |
|
||||
| Notification vendor | ✓ | — | — | Delivery infrastructure |
|
||||
| Technicians' union | — | ✓ | — | Effectively holds P at two enterprise accounts |
|
||||
|
||||
**Gap found:** Legal and the union both hold **P** and neither appeared in the first two minutes of
|
||||
Step 1. They were added late — which is the finding. The team's default is to name people who build
|
||||
and buy, not people who can stop it.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Equity lens
|
||||
|
||||
- **Who bears cost without power?** **Field technicians.** The feature makes their location visible
|
||||
to a third party. They don't buy the product, can't opt out, and weren't consulted.
|
||||
- **Whose perspective is missing because we assumed someone represents them?** We assumed the
|
||||
business owner speaks for technicians. On a surveillance-adjacent feature, that assumption is
|
||||
clearly wrong.
|
||||
- **Third-degree affected?** End customers' household members, who may be home when a tracked
|
||||
technician arrives.
|
||||
|
||||
**Added:** field technicians promoted from a passing mention to a priority stakeholder.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Bias check
|
||||
|
||||
- **Who did we default to naming?** Buyers and builders. The first eight names were all people who
|
||||
pay us or work here.
|
||||
- **Who was absent, and why?** Technicians and Legal. Technicians because they're not the buyer;
|
||||
Legal because we think of them as a late gate rather than a stakeholder.
|
||||
- **What did we assume?** That "the customer" means the business owner. Three different people in
|
||||
this initiative could be called the customer.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Priority targets
|
||||
|
||||
| Name | Category | R/P/D | What we need to learn |
|
||||
|---|---|---|---|
|
||||
| Field technicians | Audience + Influencer | — | Where the line sits between "customer knows when I'll arrive" and "my employer tracks me all day" |
|
||||
| Legal | Influencer | P | What disclosure and consent are required, and whether consent must come from the technician or the employer |
|
||||
| Service business owners | Ally + Influencer | P, D | Whether they'd adopt if technicians push back, and whether they've promised customers this already |
|
||||
|
||||
---
|
||||
|
||||
## What to notice
|
||||
|
||||
- **The equity lens changed the plan.** Field technicians went from a footnote to a priority target,
|
||||
and that single move probably prevented shipping a feature that gets escalated as surveillance.
|
||||
- **The gap test earned its place.** Two P-holders were missed in the initial brainstorm. Both could
|
||||
have blocked launch after build.
|
||||
- **The bias check was specific.** "We default to buyers and builders" is actionable; "we should be
|
||||
more inclusive" isn't.
|
||||
- **Three priority targets, each with a real question.** "Where the line sits between knowing an ETA
|
||||
and being tracked all day" is a research question. "Understand technician needs" is not.
|
||||
@@ -0,0 +1,127 @@
|
||||
# Stakeholder Identification Template
|
||||
|
||||
Six steps, one worksheet each. Quality checks at the bottom.
|
||||
|
||||
## Provenance
|
||||
Adapted from `prompts/` in the
|
||||
[product-manager-prompts](https://github.com/deanpeters/product-manager-prompts) repo.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Brainstorm without filtering
|
||||
|
||||
Four to six minutes, silent if in a group. Do not evaluate yet — evaluating during generation is
|
||||
what produces a list of the same eight people every time.
|
||||
|
||||
```markdown
|
||||
## Stakeholder Brainstorm: [Initiative]
|
||||
|
||||
Individuals, teams, organizations, and groups:
|
||||
- [name or role]
|
||||
- [name or role]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Categorize
|
||||
|
||||
A stakeholder can appear in more than one column. **The overlaps are the interesting part** — an
|
||||
ally who is also a gatekeeper is a different relationship than either alone.
|
||||
|
||||
```markdown
|
||||
| Stakeholder | Ally | Audience | Influencer |
|
||||
|---|---|---|---|
|
||||
| [who] | ✓ | | ✓ |
|
||||
```
|
||||
|
||||
- **Allies** — actively support this, or benefit from its success
|
||||
- **Audiences** — impacted by the outcome, directly or indirectly
|
||||
- **Influencers** — shape decisions, opinion, or adoption without participating directly
|
||||
|
||||
---
|
||||
|
||||
## Step 3: R/P/D marking
|
||||
|
||||
```markdown
|
||||
| Stakeholder | R (Resources) | P (Permission) | D (Decision) | Notes |
|
||||
|---|---|---|---|---|
|
||||
| [who] | budget/data/access | approval/sign-off | final say | |
|
||||
```
|
||||
|
||||
**The gap test:** anyone holding **P** or **D** who wasn't in your Step 1 list is a gap that will
|
||||
surface later as a blocked launch. Add them now and note that you missed them — the pattern of who
|
||||
you forget is itself information.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Equity lens
|
||||
|
||||
```markdown
|
||||
### Equity Lens
|
||||
|
||||
- Who experiences a significant consequence — financially, professionally, or personally?
|
||||
- Who bears the product's costs or risks **without power to shape its design**?
|
||||
- Whose perspective is missing because we assumed someone else represents them?
|
||||
- Primary users? Secondary users? Affected in the third degree?
|
||||
|
||||
**Added by this lens:**
|
||||
- [who, and what consequence they bear]
|
||||
```
|
||||
|
||||
Stakeholders surfaced here usually land in Q1 of a stakeholder map — high impact, low power — and
|
||||
are the ones most likely to be discovered late.
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Bias and assumptions
|
||||
|
||||
```markdown
|
||||
### Bias Check
|
||||
|
||||
- Who did we default to naming first? [answer]
|
||||
- Who is absent, and why? [answer]
|
||||
- What did we assume about who counts as a stakeholder? [answer]
|
||||
```
|
||||
|
||||
Record the answers. They shape the research plan and recruitment strategy, not just this list.
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Narrow to priority targets
|
||||
|
||||
Two or three. More than that isn't prioritization.
|
||||
|
||||
```markdown
|
||||
### Priority Stakeholders
|
||||
|
||||
| Name | Category | R/P/D | What we need to learn |
|
||||
|---|---|---|---|
|
||||
| | | | |
|
||||
```
|
||||
|
||||
Choose from:
|
||||
- Highest-power decision-makers whose buy-in is required
|
||||
- Highest-impact users whose needs are least understood
|
||||
- Most likely blockers or skeptics
|
||||
|
||||
---
|
||||
|
||||
## Quality checks
|
||||
|
||||
**Generation**
|
||||
- [ ] Step 1 ran without filtering — no one was excluded during brainstorm
|
||||
- [ ] The list includes people outside your organization where relevant
|
||||
|
||||
**Coverage**
|
||||
- [ ] Every P and D holder appears; any late additions are noted as gaps
|
||||
- [ ] Overlaps between categories are marked rather than forced into one column
|
||||
- [ ] The equity lens actually added someone. If it added nobody, it wasn't run honestly
|
||||
|
||||
**Honesty**
|
||||
- [ ] The bias check names a real default, not "we were thorough"
|
||||
- [ ] Someone who bears cost without power is on the list
|
||||
|
||||
**Prioritization**
|
||||
- [ ] Two or three priority targets, not eight
|
||||
- [ ] Each has a specific "what we need to learn," not "understand their needs"
|
||||
- [ ] At least one is a likely skeptic or blocker
|
||||
@@ -0,0 +1,92 @@
|
||||
# Stakeholder Mapping Example — Industrial
|
||||
|
||||
**Initiative:** Northfield Automation's remote firmware update for the NFA-500.
|
||||
|
||||
Continues from the `stakeholder-identification` industrial example, which surfaced plant OT security
|
||||
as a Permission-holder at every site.
|
||||
|
||||
---
|
||||
|
||||
## Grid 1: Power × Interest
|
||||
|
||||
| | **High Interest** | **Low Interest** |
|
||||
|---|---|---|
|
||||
| **High Power** | **Manage closely**<br>· Northfield VP Engineering<br>· Plant operations managers | **Keep satisfied**<br>· Regulatory (UL/CE)<br>· Northfield CFO |
|
||||
| **Low Power** | **Keep informed**<br>· Northfield field service<br>· Channel partners | **Monitor**<br>· Plant OT security<br>· Plant maintenance staff<br>· Plant safety officers |
|
||||
|
||||
Read alone: co-design with ops managers and engineering, brief Regulatory, inform field service and
|
||||
partners, ignore the rest.
|
||||
|
||||
---
|
||||
|
||||
## Grid 2: Impact × Power
|
||||
|
||||
| | **High Power** | **Low Power** |
|
||||
|---|---|---|
|
||||
| **High Impact** | **Q2**<br>· Plant operations managers<br>· **Plant OT security**<br>· Channel partners | **Q1 — elevate deliberately**<br>· **Plant maintenance staff**<br>· Plant safety officers |
|
||||
| **Low Impact** | **Q4**<br>· Northfield CFO<br>· Regulatory (UL/CE) | **Q3**<br>· Notification/telemetry vendor |
|
||||
|
||||
---
|
||||
|
||||
## The comparison
|
||||
|
||||
| Stakeholder | Power×Interest | Impact×Power | Tension |
|
||||
|---|---|---|---|
|
||||
| **Plant OT security** | Monitor | **Q2** | Holds Permission at every site and is deeply affected. Low expressed interest only because they haven't been told a network ingress is coming |
|
||||
| **Plant maintenance staff** | Monitor | **Q1** | A controller on their line changes state remotely; they stand at the panel when it goes wrong, with no say in enrollment |
|
||||
| Plant safety officers | Monitor | **Q1** | Own the incident review if an update contributes to an unplanned stop |
|
||||
| Regulatory | Keep satisfied | Q4 | High power, low impact — a gate, and correctly treated as one |
|
||||
| Channel partners | Keep informed | **Q2** | Higher stakes than grid 1 suggests: the feature removes billable site visits |
|
||||
|
||||
**Q1 and misplaced-Q2 voices to elevate:**
|
||||
- **Plant OT security** — the most consequential correction. Four conversations across pilot sites
|
||||
*before* the design is fixed, on what network path, authentication, and audit evidence they would
|
||||
require. They can refuse silently, site by site, and you'd never see a single "no."
|
||||
- **Plant maintenance staff** — what they need to trust a remote change: notification, veto,
|
||||
rollback visibility.
|
||||
- **Plant safety officers** — what evidence they'd need in an incident review.
|
||||
|
||||
**The mismatch that matters most:** plant OT security. Grid 1 puts them in *Monitor* — low power,
|
||||
low interest. Grid 2 puts them in **Q2**, high impact and high power, because they hold Permission
|
||||
at every site. Acting on grid 1 alone would have shipped a feature that quietly fails to be
|
||||
adoptable, one refused network request at a time, with no visible rejection anywhere.
|
||||
|
||||
---
|
||||
|
||||
## Engagement plan
|
||||
|
||||
| Stakeholder | Quadrant | Engagement | Cadence | Owner |
|
||||
|---|---|---|---|---|
|
||||
| Plant OT security | Q2 | Design consultation on network path and audit evidence | 4 sessions pre-spec | PM + Eng lead |
|
||||
| Plant maintenance staff | Q1 | Interviews, then review of the notification/veto design | Twice pre-launch | PM |
|
||||
| Plant safety officers | Q1 | Review of the incident-evidence trail | Once pre-launch | PM |
|
||||
| Plant operations managers | Q2 | Co-design, pilot cohort | Biweekly | PM |
|
||||
| Channel partners | Q2 | Commercial conversation on service-revenue impact | Monthly | Channel lead |
|
||||
| Regulatory | Q4 | Listing impact assessment | At spec, at launch | Regulatory |
|
||||
|
||||
---
|
||||
|
||||
## Quadrant migration
|
||||
|
||||
| Stakeholder | From | To | Why | How |
|
||||
|---|---|---|---|---|
|
||||
| Plant OT security | Monitor (P×I) | Manage closely | They are a silent veto at every site; involving them early converts a blocker into a specification | Bring them into design before the network path is fixed, and give them the audit evidence they ask for |
|
||||
| Channel partners | Keep informed | Manage closely | The feature removes billable visits; unaddressed, they slow adoption at accounts they service | Commercial conversation about what replaces that revenue, before launch, not after |
|
||||
|
||||
---
|
||||
|
||||
## What to notice
|
||||
|
||||
- **The most dangerous stakeholder was in *Monitor*.** OT security has no interest in your product
|
||||
and absolute authority over whether it can reach a plant. A single grid puts them last; the
|
||||
comparison puts them first.
|
||||
- **A silent veto is worse than a loud one.** OT security doesn't escalate — they decline a firewall
|
||||
change. Adoption just never materializes, and nobody can point at a rejection. That's what makes
|
||||
the mismatch expensive rather than merely wrong.
|
||||
- **Channel partners moved quadrants for commercial reasons, not process ones.** The feature removes
|
||||
revenue they currently earn. The engagement is a commercial conversation, not a briefing.
|
||||
- **Q1 here is about consequence, not convenience.** Maintenance staff and safety officers absorb
|
||||
the risk of a remote change to equipment they're responsible for. Neither has a vote in enrollment.
|
||||
- **The same pattern as the SaaS example, different stakes.** Both initiatives put the most affected,
|
||||
least powerful group in *Monitor* on the first grid. Running the second grid is what corrected it
|
||||
in both cases — which suggests the mismatch is structural, not a one-off oversight.
|
||||
@@ -0,0 +1,88 @@
|
||||
# Stakeholder Mapping Example — SaaS
|
||||
|
||||
**Initiative:** Fieldlight's customer-facing arrival windows in Next Scheduling — technician ETAs
|
||||
become visible to the end customer.
|
||||
|
||||
Continues from the `stakeholder-identification` SaaS example, which surfaced field technicians as a
|
||||
priority stakeholder.
|
||||
|
||||
---
|
||||
|
||||
## Grid 1: Power × Interest
|
||||
|
||||
| | **High Interest** | **Low Interest** |
|
||||
|---|---|---|
|
||||
| **High Power** | **Manage closely**<br>· Service business owners (the buyer)<br>· Fieldlight CPO | **Keep satisfied**<br>· Legal<br>· Fieldlight CFO |
|
||||
| **Low Power** | **Keep informed**<br>· Dispatchers<br>· Fieldlight support<br>· CS | **Monitor**<br>· Field technicians<br>· End customers<br>· Notification vendor |
|
||||
|
||||
Read alone, this grid says: co-design with business owners, brief Legal, keep dispatchers in the
|
||||
loop, and largely ignore technicians and end customers.
|
||||
|
||||
---
|
||||
|
||||
## Grid 2: Impact × Power
|
||||
|
||||
| | **High Power** | **Low Power** |
|
||||
|---|---|---|
|
||||
| **High Impact** | **Q2**<br>· Service business owners<br>· Dispatchers | **Q1 — elevate deliberately**<br>· **Field technicians**<br>· **End customers** |
|
||||
| **Low Impact** | **Q4**<br>· Fieldlight CFO<br>· Legal | **Q3**<br>· Notification vendor |
|
||||
|
||||
---
|
||||
|
||||
## The comparison
|
||||
|
||||
| Stakeholder | Power×Interest | Impact×Power | Tension |
|
||||
|---|---|---|---|
|
||||
| **Field technicians** | Monitor | **Q1** | Their location becomes visible to a third party. They have no power, low expressed interest — because nobody has told them |
|
||||
| End customers | Monitor | **Q1** | The feature exists for them; they have no voice in its design |
|
||||
| Legal | Keep satisfied | Q4 | High power, low impact — a gate, not a participant |
|
||||
| Dispatchers | Keep informed | Q2 | Higher stakes than grid 1 implies — they field the calls when a window is missed |
|
||||
|
||||
**Q1 voices to elevate:**
|
||||
- **Field technicians** — six interviews across three accounts, conducted without their employer in
|
||||
the room. Employer-present interviews on a surveillance-adjacent feature produce agreement, not
|
||||
information.
|
||||
- **End customers** — five interviews recruited through two accounts, asking what window precision
|
||||
they'd actually use versus what they'd say they want.
|
||||
|
||||
**The mismatch that matters most:** field technicians. Grid 1 says *Monitor.* Grid 2 says
|
||||
**Q1 — the most affected, least powerful group in the initiative.** Acting on grid 1 alone would
|
||||
have shipped a location-visibility feature without ever speaking to the people whose location it
|
||||
makes visible.
|
||||
|
||||
---
|
||||
|
||||
## Engagement plan
|
||||
|
||||
| Stakeholder | Quadrant | Engagement | Cadence | Owner |
|
||||
|---|---|---|---|---|
|
||||
| Field technicians | Q1 | Research interviews, then a design review with 3 techs | Twice pre-launch | PM |
|
||||
| End customers | Q1 | Concept test on window precision | Once pre-launch | Researcher |
|
||||
| Service business owners | Q2 / Manage closely | Co-design, beta cohort | Biweekly | PM |
|
||||
| Dispatchers | Q2 | Workflow walkthrough | Monthly | PM |
|
||||
| Legal | Q4 / Keep satisfied | Disclosure and consent review | At spec and at launch | PM |
|
||||
| Notification vendor | Q3 | SLA confirmation | Once | Eng lead |
|
||||
|
||||
---
|
||||
|
||||
## Quadrant migration
|
||||
|
||||
| Stakeholder | From | To | Why | How |
|
||||
|---|---|---|---|---|
|
||||
| Field technicians | Monitor (P×I) | Keep informed → consulted | They can kill adoption by escalating to their employer; consulting early converts a likely objection into design input | Two design reviews, plus naming their input in launch comms so the change is visible to them |
|
||||
|
||||
---
|
||||
|
||||
## What to notice
|
||||
|
||||
- **The two grids disagreed about the most important stakeholder.** That disagreement is the entire
|
||||
reason to run both. One grid would have produced a confident, wrong plan.
|
||||
- **Low interest was a symptom, not a preference.** Technicians showed low interest because nobody
|
||||
had told them. Treating low interest as informed disinterest is how Q1 stakeholders stay invisible
|
||||
until launch.
|
||||
- **The Q1 elevation method is specific and slightly awkward.** "Without their employer in the room"
|
||||
is the detail that makes the research worth doing.
|
||||
- **Legal sits in Q4 and that's correct.** High power, low impact — a gate to satisfy, not a
|
||||
participant to co-design with. Not every powerful stakeholder needs deep engagement.
|
||||
- **The migration names a mechanism.** Two design reviews plus visible credit in launch comms, not
|
||||
"build a relationship."
|
||||
@@ -0,0 +1,108 @@
|
||||
# Stakeholder Mapping Template
|
||||
|
||||
Two grids, then the comparison that makes running both worthwhile. Quality checks at the bottom.
|
||||
|
||||
## Provenance
|
||||
Adapted from `prompts/` in the
|
||||
[product-manager-prompts](https://github.com/deanpeters/product-manager-prompts) repo.
|
||||
|
||||
---
|
||||
|
||||
## Grid 1: Power × Interest — how to engage
|
||||
|
||||
```markdown
|
||||
## Power × Interest: [Initiative]
|
||||
|
||||
| | **High Interest** | **Low Interest** |
|
||||
|---|---|---|
|
||||
| **High Power** | **Manage closely** — co-design, frequent touchpoints<br>· [who] | **Keep satisfied** — exec briefings, strategic framing<br>· [who] |
|
||||
| **Low Power** | **Keep informed** — demos, newsletters, transparency<br>· [who] | **Monitor** — light touch<br>· [who] |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Grid 2: Impact × Power — whose voice to elevate
|
||||
|
||||
```markdown
|
||||
## Impact × Power: [Initiative]
|
||||
|
||||
| | **High Power** | **Low Power** |
|
||||
|---|---|---|
|
||||
| **High Impact** | **Q2** — impacted and empowered; manage closely<br>· [who] | **Q1** — impacted but marginalized; **elevate deliberately**<br>· [who] |
|
||||
| **Low Impact** | **Q4** — gatekeepers; manage the relationship<br>· [who] | **Q3** — monitor, minimal investment<br>· [who] |
|
||||
```
|
||||
|
||||
**Impact is not power.** A frontline support agent has high impact and low power. An executive two
|
||||
levels removed has high power and low impact. Collapsing them into one axis is what makes a single
|
||||
grid misleading.
|
||||
|
||||
---
|
||||
|
||||
## The comparison — why you ran both
|
||||
|
||||
```markdown
|
||||
### Grid Comparison
|
||||
|
||||
| Stakeholder | Power×Interest | Impact×Power | Tension |
|
||||
|---|---|---|---|
|
||||
| [who] | Monitor | **Q1** | Low interest, high impact — they don't know this is coming |
|
||||
| [who] | Manage closely | Q4 | High power, low impact — engaged but not affected |
|
||||
|
||||
**Q1 voices to elevate:** [who, and how you'll reach them]
|
||||
|
||||
**The mismatch that matters most:** [the one stakeholder whose two placements
|
||||
disagree most, and what you'll do about it]
|
||||
```
|
||||
|
||||
**The most common and most costly mismatch:** *Monitor* on Power×Interest and *Q1* on Impact×Power.
|
||||
That's someone deeply affected who has no power and hasn't engaged — usually because nobody told
|
||||
them. The first grid alone says ignore them. The second says they'll bear the consequences.
|
||||
|
||||
---
|
||||
|
||||
## Engagement plan
|
||||
|
||||
```markdown
|
||||
| Stakeholder | Quadrant | Engagement | Cadence | Owner |
|
||||
|---|---|---|---|---|
|
||||
| | | [co-design / brief / inform / consult] | | |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quadrant migration (optional)
|
||||
|
||||
For stakeholders you intend to *move* rather than merely serve.
|
||||
|
||||
```markdown
|
||||
| Stakeholder | From | To | Why | How |
|
||||
|---|---|---|---|---|
|
||||
| [who] | Keep satisfied | Manage closely | Their sponsorship unlocks budget | Bring them into design review |
|
||||
```
|
||||
|
||||
Migration is a deliberate strategy, not a hope. If you can't name the *how*, you're not migrating
|
||||
anyone.
|
||||
|
||||
---
|
||||
|
||||
## Quality checks
|
||||
|
||||
**Both grids**
|
||||
- [ ] Both were actually built — a single grid hides the mismatch that matters
|
||||
- [ ] Nobody was placed by seniority as a proxy for power
|
||||
- [ ] Impact was judged by consequence borne, not by attention paid
|
||||
|
||||
**The comparison**
|
||||
- [ ] Every stakeholder appears on both grids
|
||||
- [ ] At least one genuine tension is named. If both grids agree everywhere, one was copied
|
||||
- [ ] Q1 (high impact, low power) is populated — an empty Q1 usually means you looked only at
|
||||
people with titles
|
||||
|
||||
**Action**
|
||||
- [ ] Q1 voices have a specific elevation method, not "gather feedback"
|
||||
- [ ] Every engagement has a named owner and a cadence
|
||||
- [ ] Any migration names a concrete mechanism
|
||||
|
||||
**Honesty**
|
||||
- [ ] Someone in *Monitor* who is genuinely high-impact has been reconsidered
|
||||
- [ ] The plan is executable by the people named, at the cadence named
|
||||
@@ -0,0 +1,73 @@
|
||||
# User Story Map Example — Industrial
|
||||
|
||||
A story map for **Northfield Automation's** NFA-500 commissioning experience — the work a systems
|
||||
integrator does to get a controller installed, configured, and running on a customer's line.
|
||||
|
||||
**The industrial twist:** the backbone spans days and sites, not minutes and screens. Some steps
|
||||
happen in a shop, some in a plant, and some at 2am. And release slices are constrained by physical
|
||||
delivery — you can't ship half a controller.
|
||||
|
||||
---
|
||||
|
||||
```markdown
|
||||
## User Story Map: NFA-500 Commissioning
|
||||
|
||||
### Backbone (integrator's workflow, left to right)
|
||||
|
||||
Specify -> Configure in shop -> Install on site -> Commission -> Hand off -> Support
|
||||
|
||||
### Walking Skeleton (release 1 — the thinnest path that works end to end)
|
||||
|
||||
| Specify | Configure | Install | Commission | Hand off | Support |
|
||||
|---|---|---|---|---|---|
|
||||
| Select I/O modules for channel count | Build config on a laptop | Mount in panel with standard kit | Verify each I/O point | Print point list for plant | Read fault codes at panel |
|
||||
|
||||
### Release 2 — reduce rework
|
||||
|
||||
| Specify | Configure | Install | Commission | Hand off | Support |
|
||||
|---|---|---|---|---|---|
|
||||
| Validate module mix against panel space | Import config from a previous job | Verify wiring before power-up | Auto-test all points in sequence | Generate handoff doc | Export fault history |
|
||||
|
||||
### Release 3 — scale across jobs
|
||||
|
||||
| Specify | Configure | Install | Commission | Hand off | Support |
|
||||
|---|---|---|---|---|---|
|
||||
| Quote generator from line survey | Config templates by machine type | Guided install checklist | Remote witness for sign-off | Plant training mode | Remote firmware update |
|
||||
|
||||
---
|
||||
|
||||
### Detail under one backbone step: Commission
|
||||
|
||||
**Verify each I/O point** (R1)
|
||||
- Toggle output and confirm at the device
|
||||
- Trigger input and confirm at the controller
|
||||
- Record pass/fail per point
|
||||
|
||||
**Auto-test all points in sequence** (R2)
|
||||
- Run the full point list unattended
|
||||
- Flag failures with slot and point number
|
||||
- Produce a signed test record
|
||||
|
||||
**Remote witness for sign-off** (R3)
|
||||
- Customer engineer observes the test remotely
|
||||
- Test record signed without a second site visit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What this map teaches that the SaaS one can't
|
||||
|
||||
- **The walking skeleton is genuinely thin, and it's still a real job.** Release 1 commissions a
|
||||
controller manually, point by point, with a printed list. Slow, and it works end to end — which
|
||||
is the test of a walking skeleton. A SaaS map can slice thinner; here the floor is "the line runs."
|
||||
- **Release slices follow economics, not screens.** R2 targets rework (the expensive failure in
|
||||
commissioning), R3 targets scale across jobs. Neither is a feature grouping.
|
||||
- **One backbone step spans two locations and two organizations.** "Commission" happens on the
|
||||
customer's floor, performed by an integrator, witnessed by a plant engineer. Mapping it as a
|
||||
single actor's task would have hidden the sign-off step entirely — which is where R3's value is.
|
||||
- **The last column is where the product lives longest.** Support runs for a decade after
|
||||
commissioning ends. Story maps that stop at "hand off" systematically under-serve the phase with
|
||||
the most cumulative user-hours.
|
||||
- **Remote witness (R3) is a workflow change disguised as a feature.** It removes a site visit from
|
||||
the customer's engineer, not the integrator's. Mapping across both actors is what made that
|
||||
visible.
|
||||
@@ -0,0 +1,104 @@
|
||||
# User Story Splitting Examples — Industrial
|
||||
|
||||
Splitting oversized stories on **Northfield Automation's** NFA-500 platform.
|
||||
|
||||
**The industrial twist:** the usual tempting split — frontend/backend, or firmware/console — is
|
||||
especially wrong here, because a firmware-only slice ships nothing a customer can use and a
|
||||
console-only slice has nothing to talk to. Worse, firmware releases are expensive and infrequent, so
|
||||
a bad split can strand a half-feature in the field for a quarter.
|
||||
|
||||
---
|
||||
|
||||
## Example 1: Splitting by Workflow Steps
|
||||
|
||||
**Original Story:**
|
||||
```markdown
|
||||
As a field service technician, I want to manage firmware across my installed base
|
||||
so that units stay current without site visits.
|
||||
```
|
||||
Too big: spans enrollment, visibility, updating, and rollback.
|
||||
|
||||
**Split:**
|
||||
1. **See firmware version** for each enrolled unit in the service console
|
||||
2. **Enroll a unit** in remote management during commissioning
|
||||
3. **Push an update** to one enrolled unit during a maintenance window
|
||||
4. **Push to a group** of units on the same schedule
|
||||
5. **Roll back automatically** when an update fails mid-apply
|
||||
|
||||
**Why this works:** each slice is independently useful. Slice 1 alone answers "which units are
|
||||
behind?" — a question techs ask weekly — and it ships without touching firmware at all.
|
||||
|
||||
**The sequencing trap:** slice 5 looks like error handling to defer. It cannot be. Slice 3 must not
|
||||
ship without it, because a failed update on an un-rolled-back controller stops a production line.
|
||||
**In this domain the failure path is part of the walking skeleton, not a follow-up.**
|
||||
|
||||
---
|
||||
|
||||
## Example 2: Splitting by Business Rule
|
||||
|
||||
**Original Story:**
|
||||
```markdown
|
||||
As a technician, I want the controller to refuse unsafe operations
|
||||
so that I cannot accidentally stop a running line.
|
||||
```
|
||||
|
||||
**Split by rule:**
|
||||
1. Refuse firmware push when the line is **running**
|
||||
2. Refuse firmware push when the unit reports an **active fault**
|
||||
3. Refuse configuration change when the unit is in a **safety-interlocked state**
|
||||
4. Allow **override with explicit confirmation** for units in maintenance mode
|
||||
|
||||
**Why this works:** each rule is independently testable and independently valuable. Rule 1 alone
|
||||
prevents the most likely accident.
|
||||
|
||||
**Note on rule 4:** an override is a separate story on purpose. Bundled into rules 1-3, "refuse
|
||||
unless overridden" gets built as one permissive path and the refusal becomes advisory. Split out,
|
||||
the refusal ships strict first and the override arrives as a deliberate decision with its own
|
||||
review.
|
||||
|
||||
---
|
||||
|
||||
## Example 3: Splitting by Hardware Variant
|
||||
|
||||
A split that has no clean SaaS equivalent.
|
||||
|
||||
**Original Story:**
|
||||
```markdown
|
||||
As a technician, I want fault isolation on the front panel
|
||||
so that I know which module failed.
|
||||
```
|
||||
|
||||
**Split by variant:**
|
||||
1. Fault isolation on the **4-slot base unit** (the highest-volume configuration)
|
||||
2. Fault isolation on the **8-slot expanded unit**
|
||||
3. Fault isolation for **third-party modules** in a mixed configuration
|
||||
|
||||
**Why this works:** slice 1 covers the majority of the installed base and can ship on the existing
|
||||
panel hardware. Slice 2 needs a display change. Slice 3 depends on data third parties may not
|
||||
expose — genuinely risky, and worth isolating so it can't sink the first two.
|
||||
|
||||
**The trap this avoids:** "support all configurations" as one story means the hardest variant sets
|
||||
the timeline for the easiest, and the highest-volume customers wait on an edge case.
|
||||
|
||||
---
|
||||
|
||||
## ❌ The Split to Avoid: By Component
|
||||
|
||||
**Tempting split:**
|
||||
1. Firmware: detect and report slot-level faults
|
||||
2. Console: display fault data
|
||||
3. Panel: add slot indicators
|
||||
|
||||
**Why this is wrong:**
|
||||
- **No slice delivers anything alone.** Firmware that reports to nothing, a console with no data,
|
||||
indicators with nothing driving them
|
||||
- **Nothing is demonstrable** until all three land, so you learn nothing until you've spent
|
||||
everything
|
||||
- **It's especially costly here.** Firmware release windows are infrequent; shipping slice 1 alone
|
||||
means a firmware revision in the field that does nothing observable, and you'll need another
|
||||
revision to make it useful
|
||||
- It splits by **who does the work**, not by what a user gets — the most common splitting mistake in
|
||||
any domain, and the most expensive one in this one
|
||||
|
||||
**The fix:** Example 3's variant split. Every slice crosses firmware, console, and panel together
|
||||
for a narrower set of hardware — thin in scope, complete in function.
|
||||
Reference in New Issue
Block a user