ship-discover
Skill1 starsChanged 7 months agoMITView on GitHub
Interactive requirements gathering through structured Q&A with the user. Extracts features, user flows, data model, integrations, constraints, and non-goals. Produces CONTEXT.md. Must run after /bayes-ship:ship-new.
In this repository43 other files it gives its agents.
- accessibilitySkill
- agent-evalSkill
- agentic-engineeringSkill
- ai-regression-testingSkill
- api-designSkill
- atomic-planningSkill
- backend-patternsSkill
- coding-standards-eccSkill
- context-engineeringSkill
- frontend-patternsSkill
- git-worktreesSkill
- langchain-dependenciesSkill
- langchain-fundamentalsSkill
- langchain-middlewareSkill
- langchain-ragSkill
- langgraph-fundamentalsSkill
- langgraph-persistenceSkill
- minimalist-skillSkill
- output-skillSkill
- redesign-skillSkill
- security-scanSkill
- ship-architectSkill
- ship-autoSkill
- ship-bugfixSkill
- ship-deploySkill
- ship-executeSkill
- ship-finish-branchSkill
- ship-newSkill
- ship-planSkill
- ship-researchSkill
- ship-resumeSkill
- ship-reviewSkill
- ship-settingsSkill
- ship-specSkill
- ship-statusSkill
- ship-testSkill
- ship-worktreeSkill
- soft-skillSkill
- systematic-debuggingSkill
- taste-skillSkill
- test-driven-developmentSkill
- two-stage-reviewSkill
- verification-before-completionSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 11 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈11
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 9
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until the user has approved …
- Very specific: line 14
Read .claude/state/PROJECT.md.
- Distinctive: line 20
Before asking detailed questions, assess scope.
- Distinctive: line 24
If the project is too large for a single spec, help the user decompose into sub-projects.
- Distinctive: line 28
If upcoming questions may involve visual content (mockups, layout choices, architecture diagrams), offer the visual companion once:
- Very specific: line 36
Ask questions ONE AT A TIME.
- Distinctive: line 48
After all areas are covered, present a summary of everything captured and ask:
- Very specific: line 58
Write .claude/state/CONTEXT.md with all captured requirements organized by the 6 areas above.
- Very specific: line 60
Update .claude/state/progress.json: set phases.discovery.status to "complete" with timestamp.
- Very specific: line 66
If the user has set discover_mode to "assumptions" in /bayes-ship:ship-settings, switch to assumptions mode:
- Distinctive: line 67
Read existing code, docs, and PROJECT.md
- Distinctive: line 69
Ask the user to correct only what is wrong
- Distinctive: line 70
Write CONTEXT.md from the assumptions + corrections
- Distinctive: line 74
NEVER assume. If ambiguous, ask.
- Distinctive: line 75
NEVER suggest implementation details (that is the Architect's job).
- Distinctive: line 77
After each answer, briefly acknowledge what was captured before asking the next question.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Discovery — Interactive requirements gathering
<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until the user has approved the design. This is enforced, not suggested.
</HARD-GATE>Pre-condition
Read .claude/state/PROJECT.md. If it does not exist, tell the user to run /bayes-ship:ship-new first.
Process
Step 1: Scope assessment
Before asking detailed questions, assess scope. If the request describes multiple independent subsystems (e.g., "build a platform with chat, file storage, billing, and analytics"), flag this immediately:
"This project has multiple independent subsystems. Before we dive into details, let's decompose into sub-projects. What are the independent pieces, how do they relate, and what order should they be built?"
If the project is too large for a single spec, help the user decompose into sub-projects. Each sub-project gets its own spec, plan, and implementation cycle. Then proceed to discover the first sub-project.
Step 2: Visual companion offer
If upcoming questions may involve visual content (mockups, layout choices, architecture diagrams), offer the visual companion once:
"Some of what we're working on might be easier to explain if I can show it to you in a web browser. I can put together mockups, diagrams, and comparisons as we go. Want to try it?"
This offer MUST be its own message. Do not combine it with other questions. If the user declines, proceed with text-only discovery. Per question, decide whether the browser or terminal is more appropriate: layout comparisons go to browser; conceptual choices stay in terminal.
Step 3: Progressive Q&A
Ask questions ONE AT A TIME. Prefer multiple choice when possible. Use lettered options (A/B/C/D) so the user can respond quickly.
Cover these 6 areas in order:
- Core features — What must the product do? What are the key actions?
- User flows — What are the critical paths? What does the user do step by step?
- Data model — What entities exist? How do they relate?
- Integrations — M-Pesa? External APIs? Auth requirements? Third-party services?
- Constraints — Budget, timeline, regulatory (KRA/eTIMS), offline-first, mobile-responsive?
- Non-goals — What should the product explicitly NOT do in this version?
Step 4: Coverage check
After all areas are covered, present a summary of everything captured and ask:
- "Anything to add or correct?"
- A. Looks good, I'm done
- B. I want to add something
- C. I want to change something
Track coverage internally. Before writing CONTEXT.md, flag any uncovered areas.
Step 5: Write CONTEXT.md
Write .claude/state/CONTEXT.md with all captured requirements organized by the 6 areas above.
Update .claude/state/progress.json: set phases.discovery.status to "complete" with timestamp.
Output: "Ready. Run /bayes-ship:ship-research to investigate tech choices."
Assumptions mode
If the user has set discover_mode to "assumptions" in /bayes-ship:ship-settings, switch to assumptions mode:
- Read existing code, docs, and PROJECT.md
- Surface what you would do and why
- Ask the user to correct only what is wrong
- Write CONTEXT.md from the assumptions + corrections
Rules
- NEVER assume. If ambiguous, ask.
- NEVER suggest implementation details (that is the Architect's job).
- Maximum 1 question per message. Do not overwhelm.
- After each answer, briefly acknowledge what was captured before asking the next question.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.