Shipkit Why Project

None - This can be the first skill you run (even before shipkit-project-context)

Recommended order:

1. /shipkit-why-project - Define strategic vision
2. /shipkit-stage - Set project stage, constraints, and business metrics
3. /shipkit-product-discovery - Define personas & user needs
4. /shipkit-product-definition - Design solution blueprint
5. /shipkit-product-goals - Define user-outcome success criteria (P-*)

Process

Step 0: Context Shortcut

Before checking elicitation state, attempt a context-based shortcut:

1. Read available context: README.md, package.json (name, description, keywords), existing source files, any .shipkit/*.json files.
2. If sufficient context exists (README or package.json with description, or >5 source files):
   • Generate a complete why.json proposal based on what you found.
   • IMPORTANT: Keep it vision-level. The why.json captures the enduring vision and customer problem — NOT stage-specific details like target markets, curriculum scope, timeline constraints, or POC boundaries. Those belong in stage.json (via /shipkit-stage).
   • Write .shipkit/why.json directly and skip to Step 6 (confirm to user).
   • Present a summary of what was written so the user can review.
3. If insufficient context (empty project, no README, no package.json): Fall through to Step 1.

Step 1: Check if why.json Already Exists

1. Read .shipkit/why.json if it exists.
2. If it exists: read .shipkit/reviews/direction-assessment.json if present. If the latest review lists a gap against this artifact, archive the existing file to .shipkit/.archive/why.YYYY-MM-DD.json and regenerate addressing the gap. Otherwise, exit early with a "no changes needed" report — the reviewer already accepted it.
3. If no file exists: proceed to Step 2.

Step 2: Check Elicitation State

Read .shipkit/elicitation/why-project/answers.md.

Classify each A: line as real or placeholder:

• Placeholder markers: [awaiting answer], empty string, literal A: with nothing after.
• Real answer: any other non-empty content.

Then:

• All 5 core fields have real answers (Q1–Q5 → targetUsers, problem, currentState, vision, approach): synthesize .shipkit/why.json from those answers per the schema in Step 5. Update progress.json with status: complete, set completed_at and last_elicited_at to current ISO 8601 UTC timestamp. Skip to Step 6. Do NOT overwrite answers.md — the user's input is preserved as-is.
• Some core fields have real answers, others are placeholders: determine which questions still need answers. Proceed to Step 3 for those, but do NOT clobber answers.md — append a new turn header to the existing file for the unanswered questions only.
• File absent, empty, or all placeholders: proceed to Step 3 at turn 1. Safe to (over)write answers.md in Step 4 since no real content exists.

Step 3: Generate Questions

Produce questions for the current turn. Two-turn split (recommended):

Turn 1 — core foundation (Q1–Q3):

1. "Who is this project for?" (target users, audience, stakeholders) → targetUsers
2. "What problem does this solve? Why does it exist?" → problem
3. "Where are we now?" (current state: POC / MVP / Beta / Production / Starting) → currentState

Turn 2 — direction + optional (Q4–Q5 + optional): 4. "What does success look like? What's the vision?" → vision 5. "What's the approach? How are we getting there?" → approach 6. (Optional) "What are the measurable success criteria? (or skip)" → successCriteria 7. (Optional) "Any enduring constraints? (e.g., must run on mobile, no paid APIs — or skip)" → constraints 8. (Optional) "What are we explicitly NOT building? (or skip)" → nonGoals

Note on constraints: Capture only enduring project-level constraints here. Stage-specific constraints like "AU curriculum only for POC" belong in stage.json.

For optional fields (Q6–Q8): if the user skips, set the corresponding field to an empty array [].

One-turn mode is also acceptable for pilot: ask all 8 questions in a single turn if context suggests the user prefers a direct Q&A session.

Step 4: Write State Files

Write the following files. All timestamps ISO 8601 UTC.

.shipkit/elicitation/why-project/questions.md — overwrite with current turn's questions using the schema from install/shared/references/elicitation-protocol.md:

---