@geraldmaron/construct 1.0.6 → 1.0.8

package/skills/exploration/unknown-codebase-onboarding.md

@@ -0,0 +1,91 @@
+<!--
+skills/exploration/unknown-codebase-onboarding.md (Unknown Codebase Onboarding)
+Use when a specialist is operating in a new or unfamiliar codebase and
+needs a systematic path from zero context to productive contribution.
+Covers first-hour, first-day, and first-week checkpoints.
+-->
+
+# Unknown Codebase Onboarding
+
+Use when entering an unfamiliar codebase for the first time, or when the task requires understanding a system you haven't touched before.
+
+## First-hour checklist (orientation)
+
+The goal in the first hour is to build a mental model of the system's shape, not to understand every detail.
+
+**1. Start with the entry points:**
+```bash
+# What runs? What are the main binaries / services?
+ls bin/ scripts/ cmd/ src/main*
+
+# What does the README say is the first command to run?
+cat README.md | head -60
+```
+
+**2. Understand the dependency graph:**
+```bash
+cat package.json | jq '{name, version, scripts, dependencies: (.dependencies | keys), devDependencies: (.devDependencies | keys)}'
+# or: cat Cargo.toml, go.mod, pom.xml, requirements.txt
+```
+
+**3. Find the test suite:**
+```bash
+ls tests/ test/ spec/ __tests__/
+# What's the test runner? How do you run it?
+grep -i test package.json | head -5
+```
+
+**4. Find the data model:**
+```bash
+ls db/ schema/ migrations/ prisma/ models/
+# For a service: what does it store, and how is it structured?
+```
+
+**5. Trace one request end-to-end:**
+Pick the simplest happy path through the system and trace it from entry point to output. This reveals the architectural seams and where decisions live.
+
+## First-day checklist (orientation to action)
+
+**Identify the change surface:**
+- What is the most recently changed directory? (`git log --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20`)
+- What directories do most PRs touch? High-churn areas are where active work lives.
+
+**Understand the invariants:**
+- Are there comments marked `INVARIANT`, `IMPORTANT`, `DO NOT CHANGE`, or `CRITICAL`? These are the load-bearing beliefs.
+- Are there tests marked `regression` or referencing bug IDs? These document specific failure modes.
+
+**Find the configuration layer:**
+```bash
+# Environment variables the system reads
+grep -r 'process\.env\.\|os\.environ\|getenv' --include='*.js' --include='*.py' --include='*.go' | grep -v test | grep -v node_modules
+```
+
+**Identify the seams:**
+- Where does the system boundary end? What does it call out to (APIs, databases, queues)?
+- What are the contracts at those seams (types, schemas, documented expectations)?
+
+## First-week checklist (productive contribution)
+
+**Build a dependency map:**
+- Which modules are leaf nodes (pure logic, few dependencies)?
+- Which modules are hubs (imported everywhere, high coupling)?
+- Leaf nodes are safe to modify; hub changes have blast radius.
+
+**Read the ADRs and postmortems:**
+- Architecture decisions (`docs/adr/`, `decisions/`, `DECISIONS.md`) explain why the code is shaped the way it is.
+- Postmortems explain what has already broken and how the system defends against it. Don't break a defense you don't understand.
+
+**Find the test coverage gaps:**
+- Which modules have no tests? These are the highest-risk areas to modify.
+- Which tests are flaky (retry logic, `skip`, `todo`)? Unreliable tests produce unreliable confidence.
+
+**Validate your mental model:**
+- Before making a change, explain to a colleague (or write down) what the change does and why it won't break anything. If you can't explain it, you don't understand it yet.
+- After making a change, check: did any behavior you didn't intend to change actually change? Diff the test output.
+
+## Anti-patterns when onboarding
+
+- **Deep-diving before breadth-surveying**: the codebase is large; get the shape before the details.
+- **Modifying without understanding invariants**: breaking a behavior that was intentional because you didn't know why it existed.
+- **Trusting test coverage numbers**: 80% coverage means 80% of lines are executed, not that 80% of behaviors are tested.
+- **Ignoring comments with bug IDs**: comments that say `// workaround for PROJ-123` are load-bearing. Look up the issue before removing them.

package/skills/operating/change-management.md

@@ -0,0 +1,91 @@
+<!--
+skills/operating/change-management.md (Change Management)
+Use when categorizing a technical or organizational change, designing
+a rollout plan, or determining what approval gates are appropriate.
+Covers the Type 1 / Type 2 door framework, irreversibility analysis,
+and rollback planning.
+-->
+
+# Change Management
+
+Use when a change needs to be categorized by reversibility, when designing rollout gates, or when the team is uncertain how much approval process a change warrants.
+
+## Type 1 / Type 2 door framework
+
+From Jeff Bezos's 1997 Amazon shareholder letter, widely adopted in engineering practice.
+
+**Type 1 (one-way door):** irreversible or nearly irreversible decisions. Once made, you cannot easily go back. These deserve deliberation proportional to their irreversibility.
+
+**Type 2 (two-way door):** reversible decisions. If the outcome is not what you expected, you can reverse course. These should be made quickly and by the smallest appropriate team.
+
+**The error to avoid:** treating Type 2 decisions as Type 1. This is over-process and slows velocity. The inverse error (treating Type 1 as Type 2) is less common but more costly, it produces outcomes you cannot undo.
+
+## Irreversibility analysis
+
+Before applying process overhead, characterize the change:
+
+| Dimension | Questions |
+|---|---|
+| Data | Does this destroy, transform, or expose data in a way that can't be undone? |
+| External commitments | Does this change a customer-facing API, SLA, or contractual commitment? |
+| Infrastructure | Does this change cost structure, provider lock-in, or architectural constraints? |
+| Organizational | Does this change team structure, ownership, or decision authority in ways that are hard to reverse? |
+| Regulatory | Does this trigger compliance obligations that, once triggered, can't be untriggered? |
+
+A change that answers "yes" to any of these is at least partially Type 1. The more "yes" answers, the more deliberation is warranted.
+
+## Rollout gate design
+
+**Principle:** the smaller the blast radius of a failure, the fewer gates are needed before the next stage.
+
+**Standard progressive rollout:**
+1. Shadow (traffic mirroring, no user impact)
+2. Canary (1-5% of traffic, monitored closely)
+3. Staged (10% → 25% → 50% → 100%, with soak time at each stage)
+4. Full rollout
+
+**Gate criteria (decide before rollout starts):**
+- What metrics are you watching?
+- What threshold triggers a rollback?
+- Who has authority to advance to the next stage?
+- Who has authority to pause or roll back?
+
+Gates without pre-defined criteria become political. Define the criteria before anyone has invested in the outcome.
+
+## Rollback planning
+
+**Rule:** if you don't have a rollback plan before you deploy, you don't have a plan.
+
+**Rollback plan minimum:**
+- What is the rollback action (revert deploy, run migration-down, disable feature flag)?
+- How long does rollback take?
+- Is there a data migration that can't be reversed? If so, what's the strategy?
+- Who executes the rollback, and how are they notified?
+
+**Rollback triggers:**
+- Define in terms of observable signals, not opinions. "Error rate > 1% for 5 minutes" is a trigger. "Things feel wrong" is not.
+
+## Approval gates
+
+**For Type 2 changes:** the default should be no approval gate, or approval by the team lead. Adding approval gates to reversible changes is a tax on velocity that buys nothing.
+
+**For Type 1 changes:** approval gates should match the scope of irreversibility:
+- Data schema changes with a migration: DBA or senior engineer review.
+- External API changes: product owner + customer success (customer impact).
+- Infrastructure changes with cost implications: engineering lead + finance stakeholder.
+- Organizational restructuring: executive sponsor.
+
+**Anti-pattern:** using approval gates as a substitute for design review. Gates check whether the change is approved; they don't improve the quality of the change. Design review should happen before the gate, not at it.
+
+## Communication plan
+
+For any change with external impact, the communication plan is part of the change plan.
+
+**Minimum elements:**
+- Who needs to know (customers, partners, other teams)?
+- When do they need to know (before, during, or after the change)?
+- What channel (email, status page, in-product, account team)?
+- What's the message (what changed, why, what they need to do)?
+- Who owns the communication?
+
+For Type 1 changes, write the communication before executing the change, not after.

package/skills/operating/incident-response.md

@@ -0,0 +1,75 @@
+<!--
+skills/operating/incident-response.md (Incident Response)
+Use when a production issue is active, when drafting incident process,
+or when running a postmortem. Covers severity tiers, war-room roles,
+communication cadence, blameless postmortem structure, and MTTR
+discipline.
+-->
+
+# Incident Response
+
+Use when an issue is active in production, when building incident process from scratch, or when reviewing postmortems for quality.
+
+## Severity tiers
+
+Define tiers in terms of customer impact, not system state. A database at 80% CPU is not an incident; a checkout flow returning 500s is.
+
+| Tier | Customer impact | Response time | Escalation |
+|---|---|---|---|
+| SEV-1 | Complete outage or data loss for any customers | Immediate; all-hands | CEO, CTO, on-call lead in 15 min |
+| SEV-2 | Significant degradation affecting >10% of users or a critical path | Within 15 min | On-call lead, product lead |
+| SEV-3 | Partial degradation, workaround exists | Within 1 hour | On-call engineer |
+| SEV-4 | Minor issue, no customer impact yet | Next business day | Backlog |
+
+Sev assignment belongs to the incident commander, not the engineer who discovered it.
+
+## War-room roles
+
+Assign these before the call gets noisy:
+
+- **Incident commander (IC)**: owns the decision tree. Delegates; does not debug. Calls the all-clear. One person only.
+- **Technical lead**: owns diagnosis and remediation. Reports status to IC every 10 minutes.
+- **Comms lead**: owns customer-facing status page updates and internal stakeholder messages. Never blocks on perfect information.
+- **Scribe**: documents timeline, decisions, and action items in real time. Even partial notes are better than none.
+
+Rule: if someone doesn't have a role, they should be a silent observer or leave the call.
+
+## Communication cadence
+
+**During the incident:**
+- External: update status page within 5 minutes of SEV-1 declaration, then every 30 minutes. "We are investigating an issue affecting X" is always better than silence.
+- Internal: Slack incident channel, pinned message, updated on same cadence.
+- Escalation: when ETA to resolution is unknown after 30 minutes, escalate one level.
+
+**External message template:**
+> We are aware of an issue affecting [feature/service]. Our team is actively investigating. We will provide an update by [time]. [Link to status page]
+
+Never estimate resolution time in external comms unless you have high confidence. "By 3pm PT" that slips twice destroys trust faster than silence.
+
+## MTTR discipline
+
+Mean time to recovery is the metric that matters during an incident. Every step in the response should be evaluated by: "does this reduce MTTR or not?"
+
+Common MTTR killers:
+- Running full diagnosis before attempting rollback (rollback first, understand later)
+- Waiting for approval from someone not on the call
+- Unclear ownership of the remediation step
+- Comms blocking on engineering (they should run in parallel)
+
+**Rollback-first rule:** for software incidents, the fastest path to recovery is almost always reverting the most recent change. Diagnose the root cause after the customer impact is gone.
+
+## Blameless postmortem structure
+
+Blameless means the analysis focuses on systems and processes, not on individual error. The goal is improvements that prevent recurrence, not punishment.
+
+**Required sections:**
+1. **Timeline**: minute-by-minute reconstruction. Include when monitoring alerted, when the first human noticed, when diagnosis began, when remediation started, when recovery was confirmed.
+2. **Impact**: quantified customer impact (users affected, revenue at risk, SLA breached or not).
+3. **Root cause**: the systemic factor that made this failure possible. Not "human error", that's never a root cause. Ask "why was this configuration possible?" not "why did the engineer misconfigure it?"
+4. **Contributing factors**: secondary conditions that amplified impact or delayed recovery.
+5. **Action items**: each item has an owner and a due date. No owner = no item.
+
+**Five-whys for root cause:**
+Ask "why" five times until you reach a system-level explanation. Stop when you hit something that a process, test, or monitoring improvement can address.
+
+**Distribution:** share postmortems broadly (engineering-wide, leadership summary). Hoarding postmortems prevents organizational learning.

package/skills/operating/oncall-rotation.md

@@ -0,0 +1,95 @@
+<!--
+skills/operating/oncall-rotation.md (On-Call Rotation)
+Use when designing an on-call schedule, reviewing runbook quality, or
+handling escalation protocols. Covers handoff structure, runbook quality
+bar, escalation chains, and on-call health indicators.
+-->
+
+# On-Call Rotation
+
+Use when setting up on-call, reviewing its health, or handling an escalation during a rotation.
+
+## Rotation design
+
+**Coverage model options:**
+
+- **Follow-the-sun**: different engineers cover different time zones. Requires team distribution across 3+ time zones to avoid coverage gaps. Reduces overnight pages.
+- **Single-shift**: one engineer covers a full week. Simpler coordination. Works for small teams where follow-the-sun isn't viable. Requires enforced recovery time after high-incident weeks.
+- **Paired on-call**: primary + secondary. Secondary only engages if primary doesn't acknowledge within N minutes. Reduces burnout from false alarms; adds coordination cost.
+
+**Rotation length:**
+- 1 week per rotation is the industry standard for teams with reasonable incident rates.
+- Longer rotations (2 weeks) reduce context-switching but increase risk of burnout during high-incident periods.
+- Short rotations (<1 week) reduce individual exposure but increase handoff overhead.
+
+**On-call health indicators:**
+- Average pages per shift: >5 actionable pages/week is a process smell; >10 is a reliability emergency.
+- False alarm rate: >30% of pages should not have paged are training the team to ignore alerts.
+- After-hours page frequency: tracking this over time is how you build the case for reliability investment.
+
+## Runbook quality bar
+
+A runbook that takes more than 5 minutes to find the right section has failed its design goal. A runbook that can't be followed by a new engineer at 2am has also failed.
+
+**Required sections for every runbook:**
+1. **Alert description**: what fired, what it measures, what threshold triggered it.
+2. **Impact assessment**: how to determine customer impact (which metrics to check, which queries to run).
+3. **Triage steps**: concrete commands or links in priority order. Not explanations; steps.
+4. **Escalation path**: who to page next if triage doesn't resolve within 30 minutes. Named people with contact method.
+5. **Common resolutions**: the 3-5 fixes that cover 80% of this alert's pages. Link to rollback procedure.
+6. **Related alerts**: alerts that fire together with this one; the combination often indicates the root cause faster.
+
+**Runbook review cadence:** every runbook should be reviewed and verified after each page that required it. Stale runbooks are worse than no runbooks because they create false confidence.
+
+## Handoff protocol
+
+**At shift end:**
+- Document any open or ongoing issues with current status.
+- Note any alerts that fired but were suppressed or ignored (and why).
+- Flag any systems in degraded state that might page in the next shift.
+- Confirm the incoming engineer acknowledges the handoff, async is not a handoff.
+
+**Handoff template:**
+```
+Shift: [start] → [end]
+Pages: [count] actionable, [count] false alarms
+Open issues:
+  - [issue]: current status, expected resolution, owner
+Watch items (might page):
+  - [system]: reason for concern, what to check if it fires
+Suppressed alerts:
+  - [alert]: reason suppressed, when to re-enable
+```
+
+## Escalation chain
+
+**Design principles:**
+- Every engineer on-call must know the full escalation chain before they go on.
+- Escalation should never require asking who to escalate to during an incident.
+- The escalation chain should be in the runbook, in the incident channel topic, and in the rotation documentation.
+
+**When to escalate immediately (don't wait):**
+- SEV-1 in production with no clear path to resolution within 30 minutes
+- Data loss or risk of data loss
+- Security incident or suspected breach
+- Financial impact beyond a defined threshold
+
+**Escalation anti-patterns:**
+- Escalating silently (notify the escalation path that you're escalating and why)
+- Escalating and then detaching (you're still on the call unless explicitly relieved)
+- Failing to escalate because "I don't want to wake them up", that's what the on-call contract is for
+
+## On-call health and sustainability
+
+On-call is a tax on engineering velocity. Track it explicitly.
+
+**Metrics to report monthly:**
+- Total pages per engineer per shift
+- After-hours page rate
+- Pages that required human action vs. self-resolved
+- Runbook coverage rate (pages that had a runbook vs. those that didn't)
+
+**Sustainability signals:**
+- Engineers expressing reluctance to be on-call is a signal, not a discipline issue.
+- High turnover on teams with heavy on-call burden is a reliability cost, not a people cost.
+- If on-call requires more than 10 hours/week of active response on average, the system is broken.

package/skills/operating/orchestration-reference.md

@@ -67,7 +67,7 @@ Do not duplicate skill internals inside agent prompts. Reference the relevant sk
 
 ## Agent-to-agent service contracts
 
-Every producer→consumer pair has an explicit contract in `agents/contracts.json`, loaded via `lib/agent-contracts.mjs`. Specialists call the MCP tool `agent_contract` at the start of a handoff to see:
+Every producer→consumer pair has an explicit contract in `specialists/contracts.json`, loaded via `lib/specialist-contracts.mjs`. Specialists call the MCP tool `agent_contract` at the start of a handoff to see:
 
 - `input.mustContain`: fields the packet must carry
 - `input.schema`: JSON schema (when applicable) from `lib/schemas/`
@@ -75,7 +75,7 @@ Every producer→consumer pair has an explicit contract in `agents/contracts.jso
 - `output.schema` / `output.shape`: expected return shape
 - `postconditions`: what must be true before marking DONE
 
-Examples of contracts (full list in `agents/contracts.json`):
+Examples of contracts (full list in `specialists/contracts.json`):
 
 - `researcher-to-architect`: research brief with ≥2 primary sources → decision
 - `product-manager-to-architect`: PRD handoff → decision with Rejected alternatives

package/skills/strategy/competitive-landscape.md

@@ -0,0 +1,75 @@
+<!--
+skills/strategy/competitive-landscape.md (Competitive Landscape Analysis)
+Use when the team needs a structured read on where competitors sit, what
+customers have already decided, and where defensible whitespace exists.
+Covers Porter Five Forces, Jobs-to-be-Done framing, and competitive
+response sequencing.
+-->
+
+# Competitive Landscape Analysis
+
+Use when the team needs a structured read on market positioning before committing direction.
+
+## Porter Five Forces, applied to software products
+
+Run each force as a question, not a score. The goal is to surface which force is the
+active constraint on your strategy right now.
+
+### Threat of new entrants
+- What stops a better-funded team from replicating your core capability in 18 months?
+- Moats that compound: data flywheel, switching cost, workflow embeds, network effects. Pick the one that applies, don't claim all four.
+- Regulatory barriers (SOC 2, HIPAA, FedRAMP) are real but temporary, they slow entry, they don't stop it.
+
+### Bargaining power of suppliers
+- Model providers, cloud infrastructure, and key open-source dependencies are all suppliers.
+- Concentration risk: how many alternatives exist? What's the migration cost if one raises prices or shuts down?
+- Lock-in signals: proprietary APIs, undocumented behavior you rely on, single-vendor fine-tuning.
+
+### Bargaining power of buyers
+- SMB buyers have low switching costs and high price sensitivity. Enterprise buyers have high switching costs and low price sensitivity, but a long sales cycle to match.
+- Who actually approves the purchase? Who blocks it? These are often different people.
+- Churn rate is the revealed preference signal. "They say they like it" is not data.
+
+### Threat of substitutes
+- The substitute is rarely a direct competitor. It's the customer doing it themselves (spreadsheet, internal tool, hiring a human).
+- Ask: what does the customer do today if your product goes offline for a week? That's the substitute.
+- Substitutes get more dangerous when your segment moves upmarket and leaves the low end exposed.
+
+### Competitive rivalry
+- Crowded markets with undifferentiated offerings compete on price. Avoid this unless unit economics are exceptional.
+- Rivalry intensity signals: frequency of feature matching, public pricing wars, customer churn going peer-to-peer.
+
+## Jobs-to-be-Done framing
+
+Forces analysis tells you where power sits. JTBD tells you what customers are actually hiring your product to do.
+
+**The hire/fire framing:**
+- What job was the customer trying to get done before they found you?
+- What did they fire to hire you? (The fired solution is your real substitute.)
+- What circumstances trigger the hire? (The trigger is your acquisition moment, optimize for it.)
+
+**Functional vs. emotional vs. social jobs:**
+- Functional: the task they need to complete.
+- Emotional: how they want to feel while doing it (confident, in control, not embarrassed).
+- Social: how they want to be seen by others because of it.
+
+Enterprise B2B products often win or lose on the social job (does this make the champion look smart to their VP?).
+
+## Competitive response sequencing
+
+When a competitor moves:
+1. **Classify the move**: is this feature parity (they're catching up) or capability shift (they're changing the game)?
+2. **Test before responding**: does anyone in your current customer base care? Run a 5-customer pulse before committing resources.
+3. **Response options** (in order of cost):
+   - Ignore (if it doesn't affect the customer jobs you own)
+   - Narrate (position why your approach is intentionally different)
+   - Match (only if the feature addresses a job you claim to own)
+   - Leapfrog (only if you have a structural advantage, don't out-resource a well-funded competitor on a feature race)
+
+## Whitespace identification
+
+Whitespace is where customers have unsatisfied jobs your segment ignores.
+
+- Run a win/loss analysis on the last 20 closed deals. What patterns explain the losses that weren't price-based?
+- Look at the jobs customers do in adjacent tools after they close the loop in yours. That adjacency is the whitespace.
+- Validate with a demand signal before building: can you pre-sell, get letters of intent, or get named demand from 3+ distinct customers?

package/skills/strategy/market-research-methods.md

@@ -0,0 +1,87 @@
+<!--
+skills/strategy/market-research-methods.md (Market Research Methods)
+Use when planning customer discovery, validating product direction, or
+sizing a market. Covers qualitative and quantitative methods, JTBD
+interview technique, survey design traps, and research-to-decision
+handoff.
+-->
+
+# Market Research Methods
+
+Use when the team needs to validate assumptions before committing resources, or when a decision is being made on vibes rather than signal.
+
+## Qualitative methods
+
+### Jobs-to-be-Done interviews
+
+The only interview format worth running for product direction. The goal is to understand the customer's decision story, not to collect feature requests.
+
+**Recruiting:** target customers who recently switched (to you, away from you, or to a substitute). Recent decisions produce vivid recall. Loyal long-term customers explain their current satisfaction, not their original hire.
+
+**Interview arc (30-45 minutes):**
+1. **First thought**: "When did you first realize you needed something for this?" Surfaces the trigger and timeline.
+2. **Decision story**: "Walk me through how you actually solved it." Don't ask what they want; ask what they did.
+3. **Passive looking**: "Were you looking for a solution before you found one?" Maps latent-to-active journey.
+4. **Active looking**: "What did you consider? Why did you reject each one?"
+5. **First use**: "What did you do right after you signed up / started using it?"
+6. **Anxiety and progress**: "What worried you? What made you feel it was working?"
+
+**Anti-patterns:**
+- "What features would you want?", produces a wish list, not a decision signal.
+- Leading with your solution, contaminates the demand signal.
+- Asking about the future, customers are poor forecasters of their own behavior.
+
+### Contextual inquiry
+
+Observe customers doing the job in their actual environment. Watch for workarounds, handoffs to other tools, and moments of friction that they've normalized and won't mention in an interview.
+
+## Quantitative methods
+
+### Survey design
+
+Surveys measure prevalence of known patterns, not discovery. Run qualitative first.
+
+**Scale rules:**
+- Use 5-point Likert for agreement/frequency; 7-point for satisfaction/importance.
+- Anchor both ends explicitly: "1 = strongly disagree, 5 = strongly agree."
+- Randomize option order for non-ordinal questions to reduce position bias.
+
+**Question traps to avoid:**
+- Double-barreled: "Is the product fast and easy to use?", one question, two dimensions.
+- Leading: "How much do you enjoy using…?", primes positive response.
+- Hypothetical: "Would you use this feature?", intent ≠ behavior; use price or time-tradeoff framing instead.
+- Recall over 90 days, reliability drops sharply.
+
+**Sample sizes:**
+- Directional signal (±10 pp): n ≥ 100
+- Decision-grade (±5 pp): n ≥ 400
+- Segment cuts multiply requirements: each additional segment you want to analyze independently needs its own sample size.
+
+### Instrumentation and behavioral data
+
+Behavioral data is the gold standard because it captures revealed preference, not stated preference.
+
+Key instrumentation contracts:
+- **Activation event**: the single action that predicts retention at 30 days (find this via cohort analysis).
+- **Engagement breadth**: how many distinct features does a retained user touch?
+- **Time-to-value**: how long from signup to activation event? Optimize this before optimizing acquisition.
+
+## Market sizing
+
+Use TAM/SAM/SOM only as a forcing function for conversation, not as a precision forecast.
+
+- **TAM** (total addressable market): the revenue available if you had 100% of every relevant customer.
+- **SAM** (serviceable addressable market): the segment you can reach with your current GTM.
+- **SOM** (serviceable obtainable market): what you can realistically capture in 18-24 months.
+
+**Bottom-up sizing is more credible than top-down:**
+- Count the buyers, estimate the contract value, model conversion rate.
+- "X% of a $Y billion market" tells investors nothing about why you'll capture it.
+
+## Research-to-decision handoff
+
+Research is only valuable when it changes a decision. Before fielding any study, answer: "What decision will this inform, and what finding would change our plan?"
+
+Document as: "If we find [X], we will [action]. If we find [Y], we will [different action]."
+
+If both answers lead to the same action, skip the research.

package/skills/strategy/narrative-arc.md

@@ -0,0 +1,77 @@
+<!--
+skills/strategy/narrative-arc.md (Strategic Narrative Construction)
+Use when drafting a strategy memo, PRD positioning section, board update,
+or fundraising narrative. Covers Andy Raskin's strategic narrative
+structure, the five components of a compelling story, and common failure
+modes in executive communication.
+-->
+
+# Strategic Narrative Construction
+
+Use when the argument must move people, not just inform them. Strategic narrative is the difference between a document that gets read and one that changes what people do.
+
+## Andy Raskin's five-move structure
+
+The most replicable framework for B2B strategic narrative. Originates from Raskin's coaching of Salesforce, Zuora, and Gong.
+
+### Move 1: Name the undeniable shift
+
+Identify a shift in the world that is already happening and that everyone in the room can recognize as real. Do not start with your product. Start with the world changing.
+
+> "Buyers now do 70% of their research before contacting a vendor", not "our product helps with sales."
+
+The shift must be:
+- External (not something you caused)
+- Undeniable (skeptics can't argue it isn't happening)
+- Urgent (the implication is clear: act now or be left behind)
+
+**Common failure:** calling internal company changes a shift. "We're scaling fast" is not a shift; it's a status update.
+
+### Move 2: Name the winners and losers
+
+Who wins because of the shift? Who loses? The audience should recognize themselves in the winner column if they engage, and in the loser column if they don't.
+
+This creates stakes. Without stakes, the narrative is interesting but not motivating.
+
+### Move 3: Tease the promised land
+
+Describe the world after, what it looks like for the winner. This is the transformation, not the solution. It's a destination, not a feature.
+
+The promised land must be:
+- Specific enough to be vivid
+- Desirable to the target customer
+- Achievable with effort (not utopian)
+
+### Move 4: Introduce your capabilities as the path
+
+Only now introduce your product. Present capabilities as the specific things that make the promised land reachable. Each capability maps to an obstacle on the path.
+
+Frame as: "Here's why the promised land has been hard to reach, and here's what we built to remove that obstacle."
+
+### Move 5: Present evidence
+
+Social proof, customer stories, and data that confirm others have successfully made the journey. The evidence should feel like proof that the promised land is real and reachable.
+
+## Application to PRDs
+
+In a product requirements document, the narrative arc goes in the positioning section:
+
+- **Context** = the shift (what changed in the world or for users)
+- **Problem** = the losers (who's failing today and why)
+- **Vision** = the promised land (what success looks like)
+- **Bet** = our specific capabilities (why our approach unlocks the vision)
+- **Evidence** = research, customer signals, analogous markets
+
+## Application to board updates
+
+Board updates fail when they lead with metrics. Metrics are evidence, not story. Lead with: what changed in the world, how the company is positioned relative to that change, and what the plan is for the next 90 days.
+
+Structure: shift → where we stand → what we're doing → what we need.
+
+## Common failure modes
+
+- **Solutions looking for problems**: the narrative leads with the product. Fix by asking: "What world-shift makes this product necessary right now?"
+- **Vague promised land**: "a world where X is easier" is not vivid. Name the specific outcome, in the customer's units.
+- **Missing stakes**: if the reader can ignore the narrative without cost, there are no stakes. Make the cost of inaction visible.
+- **Evidence-free claims**: assertions without customer quotes, data, or analogous proof feel like marketing. Every claim in the arc needs a backing signal the audience can evaluate.
+- **Talking to everyone**: a narrative that is for everyone is compelling to no one. Name the specific job title, company stage, or situation the narrative is for. Everything else is wasted.