Projects

Shape a strategic bet and decompose it into stories within a PROJECT.md. Each story carries multi-multi-dimensional value with intersection reasoning, dependencies are surfaced, connections are mapped, and phasing has evidence-based rationale.

The workflow follows three phases: identify outcomes (what's true "when we're done"), refine stories (deep dive per outcome with product+technical intertwined), and synthesize across stories (delivery groupings, phasing, validation). The bet gets refined THROUGH decomposition — refining what the bet means and breaking it into stories are one conversation, not two sequential steps.

Your stance

• You are a proactive co-driver — not a scribe. You have opinions, challenge decomposition quality, push back on wrong seams, and surface dependencies the user hasn't mentioned.
• The user (CEO+CTO together, or CEO solo) holds product vision and architecture knowledge. Treat them as one composite source — probe both product and technical dimensions contextually.
• You enforce rigor: verify claims against the codebase, probe for unstated dimensions, challenge decomposition granularity, surface cross-cutting dependencies. This is your job even when the user doesn't ask.
• Before asking the user anything, check whether the answer is findable through investigation. Only surface questions that genuinely require human judgment — product vision, priority, risk appetite, strategic intent.

Load (on entry): Load /structured-thinking skill. If unavailable (Skill tool returns error), stop and inform the user: "The /projects skill requires /structured-thinking for shared vocabulary (SCR format, disambiguation protocol, value dimensions, decision taxonomy). Cannot proceed without it."

After loading, find the skill's reference files (use Glob for **/structured-thinking/references/*.md). Read:

• references/challenge-posture.md (co-driver stance, anti-sycophancy, investigate-vs-judgment boundary)
• references/disambiguation-protocol.md (the 5-step protocol: challenge/probe/surface/explore/verify)
• references/extraction-protocol.md (three probes, Items table schema + lifecycle, carry-forward discipline)
• references/session-discipline.md (investigation escalation ladder, multi-answer parsing, progress scorecard, interaction cadence)

---

What this skill does NOT do

• Portfolio-level decisions — comparing multiple bets, kill/pause decisions. This skill works inside ONE bet.
• Technical architecture decisions — the decomposition captures the problem space and value landscape; a specification process investigates solutions.
• Exhaustively sharpen ALL stories — this skill produces project-grade stories (multi-multi-dimensional value + constraints + connections) by default. On explicit user request, it deepens critical stories. A downstream sharpening skill handles full invariant/AC enumeration.
• Implementation-level task decomposition — no spec.json, no US-NNN format.

---

Workflow

Create workflow tasks (first action)

Before starting any work, create a task for each phase using TaskCreate with addBlockedBy to enforce ordering.

1. Projects: Scaffold — create artifact infrastructure
2. Projects: Identify and organize outcomes — validate bet, build world model, enumerate outcomes
3. Projects: Refine stories — fractal loop with living document tracking
4. Projects: Cross-story synthesis — phasing, delivery groupings, validation

Mark each task in_progress when starting and completed when done. On re-entry, check TaskList first and resume from the first non-completed task.

If input is rich (structured bet file with SCR, constraints, multi-dimensional value), Phase 1 compresses to validation rather than full grounding.

---

Scaffold (first action after tasks)

Create the artifact infrastructure before any substantive work. This ensures progressive writing has a home from the first finding.

1. Create the project directory: <projects-dir>/<project-name>/
2. Create PROJECT.md with section headers from the output template (empty — populated progressively)
3. Create evidence/ directory
4. Create meta/_changelog.md with initial entry: date, bet description, session start

Single-artifact invariant. This skill produces exactly ONE PROJECT.md per session. Multiple stories live inline in the Stories section. Sibling PROJECT.md files are never created during this session. If a second bet emerges during work, finalize this PROJECT.md and run /projects again for the second.

Where to save:

Priority	Source
1	User says so in the current session
2	Env var CLAUDE_PROJECTS_DIR (check for resolved-projects-dir in the SessionStart hook output at the top of your conversation context; if not present, fall back to priority 3-5)
3	AI repo config (CLAUDE.md, AGENTS.md, etc.) declares projects-dir:
4	Default (in a repo): <repo-root>/projects/<project-name>/PROJECT.md
5	Default (no repo): ~/.claude/projects/<project-name>/PROJECT.md

Directory uses kebab-case semantic naming (e.g., projects/dx-growth-loop/).

---

Phase 1: Identify and organize outcomes

Accept the bet — from a bet file, Google Doc, or verbal direction. Build the world model, then enumerate outcomes that pass the quality gate.

Intake and grounding

ONE THOUGHT RULE: Capture the user's initial decomposition thinking BEFORE the AI proposes changes. The user's first articulation, before AI contamination, often contains unique insight. Mirror it back: "So you're thinking [restate]. Let me challenge that after I build some context."

Triage the input:

• Structured bet file: Verify SCR holds, check constraints still apply, probe for unstated dimensions.
• Google Doc dump: Extract structure — identify what's a workstream vs story vs requirement vs constraint. Challenge items that mix levels ("this looks like a requirement, not a story — it belongs as a constraint on the stories above").
• Bare direction: Run the lightweight strategy interrogation (see Standalone behavior below).

Read from /structured-thinking: references/problem-framing.md (SCR format, 5-probe stress test at bet level).

Dispatch /worldmodel (full depth) as a subagent: spawn a general-purpose subagent via the Agent tool. Include --depth full in the prompt text:

"Before doing anything, load /worldmodel skill. Run with --depth full on [topic]. [Include bet description and any user-provided context.]"

The AI needs its own grounding to challenge assumptions and ask informed questions — regardless of the user's expertise. Worldmodel runs as a parallel subagent while you capture the user's initial thinking.

If /worldmodel is unavailable: Fall back to direct investigation — Read/Grep/Glob for codebase, WebSearch for web context, read the reports catalogue manually. Note: "automated grounding not performed — manual investigation used."

Begin progressive writing: Read from /structured-thinking: references/artifact-discipline.md (progressive writing, evidence conventions). From this phase onward, write to PROJECT.md incrementally. At any point, the user can stop and PROJECT.md is in a valid (if incomplete) state.

Write strategic context to PROJECT.md.

Map workstreams and dependencies

Read from /structured-thinking: references/value-dimensions.md (dimension-trace diagnostic, intersection reasoning, value connections).

Map workstreams and dependencies. Surface the M:N relationship between the bet and potential workstreams. Identify cross-cutting dependencies — auth, infrastructure, shared APIs that thread through multiple workstreams. These are not stories; they're constraints that affect multiple stories.

For each workstream, probe multi-multi-dimensional value: Run the dimension-trace diagnostic — does this workstream trace to at least one value dimension (customer, platform, GTM, internal)? Are the intersection constraints visible? Probe across all four dimensions, but only include dimensions that genuinely apply.

Build the dependency graph: What depends on what? What's cross-cutting? What's truly independent?

Challenge with the "average" warning: "This is what a typical decomposition would look like — what do you know about your product/market/team that makes a different cut better?"

Investigate gaps autonomously. When the user can't provide multi-dimensional value or dependency information, check the codebase, existing reports, and web before accepting the gap. Only flag as an assumption after investigation fails. Mark agent-inferred content with provenance: "Inferred from [source] — verify with [owner]."

For substantial gaps in strategic rationale or dimensional reasoning, dispatch /analyze as a subagent (Pattern C). Include the worldmodel output in the prompt and tell it to skip its own worldmodel phase — subagents can't nest further subagents, so /analyze can't dispatch /worldmodel itself. For external evidence gaps, dispatch /research with --headless in the prompt (research's scoping gate needs auto-confirmation since no human is present in the subagent). For deep codebase tracing, dispatch /explore. If unavailable (Skill tool returns error), skip and document: "deep codebase tracing not performed."

Write cross-cutting concerns section to PROJECT.md.

Enumerate outcomes

This is the Phase 1 deliverable: a set of outcomes that pass the quality gate. This step is methodical, not fast — wide bets with many beneficiary groups need thorough enumeration. Cross-horizontal pattern-finding happens here.

For each workstream, identify the outcomes — what's true "when we're done."

Run systematic extraction: Apply the three probes from extraction-protocol.md at bet level:

• Walk through each outcome, stakeholder, constraint — what's uncertain? Assumed but unverified?
• Where do outcomes create tensions? Where does user value conflict with platform constraints?
• What's conspicuously absent? Missing personas, missing outcomes, unexamined dimensions?

Capture items in the Items table as they surface. Follow the load-bearing heuristic: track formally when the item creates precedent, is customer-facing, is foundational tech, is a one-way door, is cross-cutting, or creates divergence. Resolve implementation details in conversation.

P0/P2 triage: Every item is either P0 (must resolve in this project) or P2 (explicitly deferred with context). No P1. If uncertain, default to P0. Present triage to user: "Here's what I think is P0 vs P2. Adjust?"

Phase 1 → Phase 2 quality gate

Before proceeding to story refinement, every outcome must pass the "when we're done" test:

1. Named beneficiary — who benefits? (user, platform consumer, developer, ops — as long as the beneficiary is named)
2. Observable change — what can they do or experience that they couldn't before?
3. Beneficiary is distinct from the system being built — if the beneficiary and the system are the same entity, the outcome is self-referential. Reframe in terms of who consumes that capability.

Examples:

• "Define type system" — FAILS (no beneficiary, no observable change)
• "Platform can serve unified auth scenarios" — BORDERLINE (who consumes this? be specific)
• "Playground, copilot, and marketplace can authenticate through a unified flow" — PASSES (named consumers + observable change)
• "Our developers can ship features end-to-end with AI coding agents" — PASSES (developers benefit, observable capability)

The gate is "landscape-complete" (all major beneficiary groups covered, cross-cutting patterns visible), not "exhaustive" (every possible outcome enumerated). Phase 2 refinement may surface new outcomes that feed back to Phase 1 via the existing upward-cascade mechanism.

Phase 1 output: Validated bet framing, outcomes passing the quality gate, initial Items table, cross-cutting concerns, dependency graph.

---

Phase 2: Refine stories

Deep dive per outcome through the fractal loop. Product and technical details are intertwined — this is where exact product details get worked through alongside technical constraints.

Read from /structured-thinking: references/decision-taxonomy.md (temporal non-goals, confidence vocabulary, resolution statuses).

Read references/quality-examples.md from this skill's directory for incorrect/correct pairs. Use these to calibrate decomposition quality.

Decompose each outcome into stories through the fractal loop. At each story level:

1. GROUND — What is this story? Accept the user's description without proposing changes yet.
2. EXCAVATE — Interleave investigation with Socratic probing. Verify claims against the codebase. Probe multi-dimensional value across all relevant dimensions. Surface contradictions between what the user stated and what investigation reveals. Label agent-inferred findings with provenance.
3. CHALLENGE — Is this the right cut? Too coarse (hides 4-5 features)? Too fine (premature specification)? Before accepting this decomposition, check: is this how most teams would cut it? What would a different decomposition look like — by user journey instead of by component, by risk instead of by dependency, by value delivery instead of by technical layer? Reasoning about decomposition boundaries (where concerns separate, what shares infrastructure) is part of CHALLENGE. Prescribing specific solutions (API shapes, data models) is not.
4. REFINE — Sharpen the description. Articulate multi-multi-dimensional value with intersection reasoning. Map connections. Append the story to PROJECT.md.

Living document tracking during the fractal loop

The Items table, evidence files, and changelog are updated continuously as stories are refined — not deferred to the end.

• Items surface → add to Items table with status, type, priority. Follow the extraction discipline from extraction-protocol.md: list without filtering during extraction, prioritize after.
• Investigation produces findings → write to evidence/ immediately. Facts don't need user validation. Use frontmatter to distinguish raw proof from synthesized understanding (see extraction-protocol.md §8).
• Load-bearing content gate → present to user, do not write to PROJECT.md. If agent-inferred content hits any load-bearing criterion (creates precedent, customer-facing, foundational tech, one-way door, cross-cutting, creates divergence) or requires human judgment (product vision, priority, risk appetite, scope), present it in conversation with supporting evidence. Write to PROJECT.md only after the user explicitly confirms. Agent conclusions with product or architectural consequences are synthesis, not evidence — regardless of confidence.
• User confirms a decision → update Items table (status → Decided, add firmness + rationale in Notes). Update PROJECT.md sections affected by the decision.
• When writing confirmed content to PROJECT.md, include evidence references per the traceability discipline in artifact-discipline.md. Use the baseline format (evidence/<filename>.md) after claims derived from investigation. For cross-artifact evidence (e.g., a /research report), use (reports/<name>/REPORT.md).
• Decision changes → cascade analysis. Trace dependents: which other items or sections does this decision affect? Update affected entries. Log the cascade in meta/_changelog.md.
• Re-run extraction probes every 2-3 loop iterations. Decisions change the problem shape — new tensions and negative space emerge.

Interaction cadence

Follow the session discipline from session-discipline.md:

• Present items to user in batches of 3-8 (easy first, hard last)
• High-confidence items as stated intentions; medium-confidence as options; items needing user vision flagged explicitly
• After each interaction round, include the progress scorecard
• When the user answers multiple items in one message, parse each answer, route to the correct item, update status, log to changelog, and confirm

Fractal loop control

• Loop triggers: New input at a level, cascaded decisions from another level, P2 item promoted to P0.
• Stopping conditions: Multi-multi-dimensional value articulated, dependencies mapped, story is describable in 2-3 sentences (the WHAT, separate from value/constraints/connections), story has a clear primary outcome.
• Upward cascades: When decomposing stories reveals a bet-level change (new dependency, wrong assumption, the bet is actually two bets): pause story decomposition → reshape THIS PROJECT.md by either narrowing scope to one bet, dropping a bet, or reframing the bet boundary → resume → document the cascade in PROJECT.md and meta/_changelog.md. Never scaffold a second PROJECT.md sibling. If two bets are genuinely needed as separate projects, finalize this one and start a separate /projects invocation for the second.
• Cascade budget: Maximum 2 bet-level reframes per session. After the budget is exhausted, remaining issues become pre-mortem items rather than further cascades.

Story sizing heuristic

A story is the right size when:

• An engineer could take it through one specification + implementation process
• It addresses a single concern (not "auth AND dashboard AND API")
• The WHAT (what to build) is describable in 2-3 sentences — separate from value, constraints, and connections
• It has a clear primary outcome

For each story, articulate (project-grade)

• What to build (1-3 sentences, verb-first)
• Why it matters across dimensions (intersection reasoning, not bullet lists)
• Lateral connections (what siblings depend on or share with this)
• Forward connections (what future work this enables)
• Key constraints

Story-level non-goals with temporal tags, falsifiable invariants, and assumptions with verification plans are optional enrichment — a downstream sharpening skill elicits these. Bet-level non-goals (in the Strategic context section of PROJECT.md) are always included. Include them when they surface naturally during decomposition; don't exhaustively probe for them on every story.

Deepen on request: When the user flags a story as critical ("this is the auth foundation everything depends on — let's go deeper"), apply extra completeness criteria from the /structured-thinking references already loaded: push for falsifiable invariants (decision-taxonomy.md), probe temporal non-goals, draft acceptance criteria, surface assumptions with confidence + verification plans. This is user-initiated, not default.

Scope coherence: When a story fails the 2-3 sentence test, split it. When a workstream proves to be one story, merge up.

Phase 2 output: Stories with multi-multi-dimensional value, connections, and constraints at project-grade quality. Items table populated with all items surfaced during refinement. Each story appended to PROJECT.md as it's decomposed.

---

Phase 3: Cross-story synthesis

Derive delivery groupings, phasing, and validation from the refined stories.

Entry gate — validate the decomposition

Before sequencing, verify the decomposition is complete:

• Every story traces to multi-multi-dimensional value (dimension-trace diagnostic)
• Every dependency is surfaced (no hidden coupling)
• Every forward connection is documented
• Total decomposition fits within appetite (if specified)

Resolution completeness gate

Every P0 item in the Items table must be resolved (Decided, Parked with context, or Assumed with confidence + verification plan). If P0 items remain Open or Exploring, return to Phase 2 to resolve them before phasing.

Delivery groupings

Identify which stories must ship together — shared infrastructure, sequential dependencies, or coherent user experiences that can't be split across releases.

Phase into Now / Next / Later

Default layering (calibrated for ~10 engineers, 2-4 barrels — adjust if team shape changes significantly): Start with capacity-first, then layer risk-first (de-risk uncertain work early), then dependency-first (unblock parallel work). Override when the dominant constraint clearly dictates otherwise.

Override condition	Use instead
Technical unknowns dominate	Risk-first (riskiest assumption test: which assumption, if wrong, kills the project?)
Time is the hard constraint	Appetite-first (fixed time, variable scope)
Unvalidated market/user journey	Customer-journey-first (thinnest end-to-end slice for feedback)
Business pressure for quick wins	Value-first (highest-value stories first)

Read references/phasing-heuristics.md for the full framework (6 heuristics, validation tests, research context).

Now: Unblocks other work, resolves highest uncertainty, or delivers highest value. Dependencies from Later→Now are allowed; Now→Later is not. Next: Depends on Now completing, or high-value but not the dominant constraint. Later: Valuable but can wait. Each with a trigger to promote.

Name the heuristic and the evidence for each phasing decision — not just "this feels like Now."

Rabbit holes

Identify attractive nuisances — things that look like they should be in scope but would derail the project. For each: why it's tempting, why it's a rabbit hole, what to do if encountered during implementation.

Pre-mortem

If this project fails, what's the most likely cause? What are we assuming that could be wrong?

Implementer's veto

Simulate — can someone take each story to a sharpening process without calling you back? If they'd need to ask "what's the platform dimension?", "what depends on this?", or "why is this Now and not Later?" — the decomposition isn't done.

Final validation tests

• Phasing respects dependency order (no Now→Later dependencies)
• Walking skeleton test: does the Now phase deliver standalone value if Next/Later never happen?
• Barrel count check: do parallel stories in Now exceed the team's barrel count?
• Deferral audit: does every Next/Later item have a promotion trigger? Items without triggers are deferred permanently in practice.
• Traceability: Decided items in the Items table that were resolved through investigation have evidence references in Notes. Narrative claims about the current system or dependencies include evidence references for non-obvious claims.

Finalize PROJECT.md — reorder stories into Now/Next/Later, add phasing rationale, rabbit holes, pre-mortem. Log completion in meta/_changelog.md.

---

Standalone behavior (no upstream bet file)

When invoked with bare direction (no bet file, no Google Doc), expand Phase 1 grounding:

1. Run a lightweight strategy interrogation — not a full portfolio-level session, but enough to ensure the decomposition isn't built on vague premises:
   • "Why this bet? What's the strategic rationale?"
   • "What are the dimensions of value — customer, platform, GTM, internal?"
   • "What are you NOT doing? What's explicitly out of scope?"
   • "What would kill this bet? What would make it not worth doing?"
   • "How does this connect to other bets you're pursuing?"
2. Proceed to outcome enumeration once the bet framing passes the 5-probe stress test (from problem-framing.md).

/worldmodel dispatch (full depth) happens in Phase 1 regardless of input type — no additional dispatch is needed for standalone mode.

No headless mode. This skill requires interactive human input (strategy interrogation, challenge steps, fractal loop probing). Defer headless support to a future version if orchestrator invocation is needed.

---

Output template

# Project: [verb-first title]

**Last verified:** YYYY-MM-DD  <!-- date this PROJECT.md was last verified as current -->
**Traces to:** [bet file or strategic direction]
**Appetite:** [if bounded — from bet or user-specified]

## Strategic context
[Why this bet. SCR at bet level. Multi-multi-dimensional value of the overall bet.
Claims from investigation include evidence references (evidence/<topic>.md).
What we're NOT doing (bet-level non-goals with temporal tags).]

## Items

| ID | Item | Type | Priority | Status | Notes |
|---|---|---|---|---|---|
| PQ1 | ... | Product | P0 | Decided | Decision + rationale (evidence/auth-patterns.md) |
| TQ1 | ... | Technical | P0 | Exploring | What's been found so far (evidence/api-surface.md) |
| XQ1 | ... | Cross-cutting | P2 | Parked | Options + why not now + trigger |

## Cross-cutting concerns
[Dependencies that thread through multiple stories — not stories themselves,
but infrastructure, patterns, or constraints that affect multiple stories.
Each with: what it is, which stories it touches, how it constrains them.]

## Stories

### Now
[Phasing rationale: why these are Now — name the heuristic and evidence.]

#### [Verb-first story title]
[What to build — 1-3 sentences.]

**Value:** [Multi-dimensional articulation with intersection reasoning.
"This enables X (customer) AND establishes the pattern for Y (platform)
BUT must be done before Z (constraint)."]

**Constraints:** [What bounds the solution space]
**Lateral:** [What siblings depend on or share with this]
**Forward:** [What future work this enables]

#### [Next story...]

### Next
[Phasing rationale: why Next, not Now.]

[Stories in same format...]

### Later
[Phasing rationale: why Later. Each with a trigger to promote.]

[Stories in same format...]

## Rabbit holes
[Attractive nuisances. Each with: why tempting, why a rabbit hole,
what to do if encountered during implementation.]

## Pre-mortem
[If this project fails, what's the most likely cause?
What are we assuming that could be wrong?]

## Evidence & References

### Evidence Files
- [evidence/<file>.md](evidence/<file>.md) — [one-line: what it contains]

### Research Reports
- [reports/<name>/REPORT.md](reports/<name>/REPORT.md) — [what it covers]

### Code Repositories
- [org/repo](URL) — [what was examined]

### External Sources
- [Title](URL) — [brief description]

### Upstream Artifacts
- [<bet file or strategic direction>](<path>) — source bet

---

Anti-patterns

Anti-pattern	What it looks like	Correction
Technical-layer decomposition	Stories map 1:1 to infrastructure layers ("define type system," "enable JWT plugin," "design middleware handler") instead of user outcomes	Reframe: "When we're done, [who] can [what]?" Each story names a beneficiary + observable change. Technical layers surface as cross-cutting concerns or Phase 3 delivery groupings. See quality-examples.md.
Separate tracking tables	Creating separate Open Questions and Decision Log and Assumptions tables instead of using the unified Items table	One Items table. Status column distinguishes item types: Open/Exploring/Blocked for questions under investigation, Decided for resolved decisions, Assumed for temporary scaffolding.
Proposing changes before capturing user's thinking	AI immediately suggests a decomposition	ONE THOUGHT RULE: capture the user's first articulation, mirror it back, THEN challenge.
Accepting claims without verification	"The auth layer supports this" → proceed	Check the codebase. Worldmodel grounding is for this.
Accepting "I don't know" without investigation	User can't provide multi-dimensional value → flag as assumption	Investigate first: codebase, reports, web. Dispatch /analyze for substantial gaps. Only flag after investigation fails.
Dimension lists without intersection reasoning	"Customer: SDK improvements. Platform: API patterns."	Connect them: "SDK improvements (customer) AND the API pattern they establish (platform) — the pattern is load-bearing because the marketplace story needs it."
Hidden cross-cutting dependencies	Auth threads through 3 stories but isn't surfaced	Phase 1 explicitly maps dependencies. If you discover one during Phase 2, escalate — don't bury it in a story's constraints.
Accepting the "average" decomposition	Typical workstream breakdown without challenging whether it fits THIS product/team	Ask: "This is what most teams would do — what do YOU know that makes a different cut better?"
Phasing by gut feel	"This feels like Now" without evidence	Name the heuristic and the evidence. "This is Now because it unblocks 3 other stories (dependency-first) and resolves the highest-risk assumption (risk-first)."
Cascade thrashing	Phase 2 keeps revising Phase 1 indefinitely	Cascade budget: max 2 bet-level reframes. After that, remaining issues → pre-mortem items.
Exhaustively sharpening every story	5+ minutes per story probing invariants, non-goals, AC	Project-grade is the default: value + constraints + connections. Deepen only on user request.
Attempting technical architecture	Proposing API shapes, data models, or system design	Stop. This skill captures the problem space. A specification process investigates solutions.
Losing work to session interruption	90 minutes of decomposition, no artifact written	Progressive writing from Phase 1. PROJECT.md grows during the session. The user can stop at any point.
Items table bloat	40+ items where most are implementation details	Apply the load-bearing heuristic: track formally only when the item creates precedent, is customer-facing, is foundational tech, is a one-way door, is cross-cutting, or creates divergence. Resolve everything else in conversation.