majiayu000 Discovery Pack Workflow
Structured project discovery using proven methodologies (JTBD, Amazon PR/FAQ, ADR, Lean Startup, DDD). Transforms ambiguous ideas into clear, validated specifications ready for spec-kit handoff.
Quick Start
Activation Triggers: "discovery", "requirements discovery", "project framing", "validate assumptions", "JTBD analysis"
Two Modes:
- Lite (3 artifacts, 15-30 min): Small projects, <5 people, low risk, personal/startup
- Full (8 artifacts, 1-2 hours): Enterprise, compliance, security-critical, high risk
Pre-Flight Check:
bash scripts/pre-flight-check.sh <output-dir> <mode>
Core Methodologies
| Methodology | Purpose | Applied In |
|---|---|---|
| Jobs-to-be-Done (JTBD) | User motivation & context | Problem framing (00) |
| Amazon PR/FAQ | Customer clarity | Problem framing (00) |
| ADR | Decision rationale | Decision log (06) |
| Lean Startup | Assumption validation | Validation plan (05) |
| DDD | Domain language | Domain model (02) |
📖 Details: shared-references/methodologies.md, shared-references/glossary.md
Installation & Paths
Supported Locations:
~/.copilot/skills/discovery-pack/(GitHub Copilot CLI)~/.claude/skills/discovery-pack/(Claude Code).claude/skills/discovery-pack/(project-local)- Any custom location (relative path resolution)
Script Invocation:
# From skill root:
python3 scripts/validate.py <output-dir>
# From anywhere:
python3 ~/.copilot/skills/discovery-pack/scripts/validate.py <output-dir>
All scripts use relative path resolution (Path(__file__) / ${BASH_SOURCE[0]}).
Workflow Orchestration
Step 1: Mode Selection (MANDATORY)
🛑 ALWAYS ask first:
| Mode | Artifacts | Time | Best For |
|---|---|---|---|
| lite | 3 (00, 03, 07) | 15-30 min | Small projects, low risk, <5 people |
| full | 8 (00-07) | 1-2 hours | Enterprise, compliance, high risk |
Decision Tree:
- Enterprise/regulated/security-critical? → full
- Multi-team/multi-stakeholder? → full
- Personal/startup/prototype? → lite
- Unsure? → lite (can upgrade later)
Automation Check:
# Optional but recommended (30-40% token savings)
pip install -r scripts/requirements.txt
Step 2: Output Directory
Target: <project-root>/docs/discovery/YYYY-MM-DD-<topic-slug>
Examples:
/docs/discovery/2026-01-07-user-auth/docs/discovery/2026-01-07-api-redesign
Auto-create if missing (scripts handle this).
Step 3: Execute Workflow
Progressive Disclosure Strategy: Load detailed workflow only when starting execution.
🔵 Lite Mode (3 artifacts)
Workflow File: shared-references/workflows/lite-mode.md
Quick Overview:
- Problem Framing (00) → Load
templates/00_problem-frame.md, fill YAML, validate - Option Analysis (03) → Load
templates/03_option-space.md, compare 2+ options, recommend - Handoff (07) → Load
templates/07_speckit-handoff.md, prepare spec-kit input
Load detailed instructions: Read shared-references/workflows/lite-mode.md before starting Phase 1.
🟣 Full Mode (8 artifacts)
Workflow File: shared-references/workflows/full-mode.md
Quick Overview:
- Problem Framing (00) → Foundation
- Constraints (01) → Security, performance, observability boundaries
- Domain Model (02) → Entities, bounded contexts, ubiquitous language
- Option Analysis (03) → Alternatives comparison
- Assumptions (04) → Auto-generated via
extract_assumptions.py - Validation Plan (05) → Experiments to test assumptions
- Decision Log (06) → ADR format decisions
- Handoff (07) → Spec-kit integration
Load detailed instructions: Read shared-references/workflows/full-mode.md before starting Phase 1.
Step 4: Validation Gate (MANDATORY)
🛑 After artifact generation:
python3 scripts/validate.py <output-dir>
Expected Output:
✅ 00_problem-frame.md: Valid
✅ 03_option-space.md: Valid
✅ 07_speckit-handoff.md: Valid
📊 Summary: 3/3 artifacts valid (100%)
If validation fails:
- Read error message (shows file + field + expected format)
- Fix YAML frontmatter (common: missing fields, wrong types, invalid enums)
- Re-validate until 100% pass
No progression without 100% validation pass (schema compliance mandatory).
Artifact Reference
| ID | Name | Lite | Full | Auto | Template |
|---|---|---|---|---|---|
| 00 | Problem Frame | ✓ | ✓ | - | templates/00_problem-frame.md |
| 01 | Constraints & NFRs | - | ✓ | - | templates/01_constraints-nfr.md |
| 02 | Domain Model | - | ✓ | - | templates/02_domain-model.md |
| 03 | Option Space | ✓ | ✓ | - | templates/03_option-space.md |
| 04 | Assumptions | - | ✓ | ✓ | Auto via extract_assumptions.py |
| 05 | Validation Plan | - | ✓ | - | templates/05_validation-plan.md |
| 06 | Decision Log | - | ✓ | - | templates/06_decision-log.md |
| 07 | Spec-Kit Handoff | ✓ | ✓ | - | templates/07_speckit-handoff.md |
Template Loading: Load template only when generating that specific artifact (progressive disclosure).
Automation Scripts
| Script | Purpose | When to Use |
|---|---|---|
scripts/pre-flight-check.sh |
Validate environment | Before starting workflow |
scripts/discovery-pack-run.sh |
Full workflow executor | Automated end-to-end execution |
scripts/validate.py |
Schema validation | After each artifact / end of workflow |
scripts/extract_assumptions.py |
Generate 04 from 00-03 | Full mode, after 00-03 complete |
scripts/ci-validate.sh |
CI/CD integration | Automated validation in pipelines |
Token Savings: Automation provides ~30-40% token reduction vs manual execution.
Quality Gates
Pre-Flight Requirements
- Mode selected (lite/full)
- Output directory determined
- Python 3.11+ available (if using automation)
- Templates accessible via relative paths
Artifact Quality
- 100% schema validation pass
- All required YAML fields present
- Epistemic tags used ([ASSUMPTION], [HYPOTHESIS], [CONSTRAINT])
- Cross-references between artifacts (e.g., 05 links to 04 assumption IDs)
Handoff Criteria
- All planned artifacts generated
- Validation passes 100%
- 07_speckit-handoff.md marks
ready_for_speckit: true - Stakeholder review complete
Token Optimization
Progressive Disclosure Pattern:
- Load workflow file only when starting execution (not upfront)
- Load template only when generating that artifact
- Load methodology details only when user asks clarifying questions
- Use automation scripts (reduces 30-40% tokens)
Target Token Budget:
- Lite mode: ≤15k tokens
- Full mode: ≤25k tokens
High Token Operations (avoid unless necessary):
- Reading all templates upfront
- Inline methodology explanations (use references)
- Verbose examples (use workflow files)
Troubleshooting
Validation Errors
| Error Type | Symptom | Fix |
|---|---|---|
| Missing field | Missing required field: X.Y.Z |
Add field to YAML frontmatter |
| Type mismatch | Expected array, got object |
Convert format (e.g., single → list) |
| Invalid enum | Value not in enum: [...] |
Use valid enum value from error |
| YAML syntax | could not parse YAML |
Check indentation, colons, quotes |
Common Issues
Scripts not found:
- Verify working directory (should be skill root)
- Or use full path:
~/.copilot/skills/discovery-pack/scripts/...
Automation unavailable:
- Install dependencies:
pip install -r scripts/requirements.txt - Or proceed manually (workflow files guide you)
Template loading fails:
- Check
templates/directory exists relative to skill root - Verify path resolution working (run
scripts/pre-flight-check.sh)
Next Steps After Discovery
- Review artifacts with stakeholders
- Execute validation experiments from 05_validation-plan.md (if full mode)
- Start spec-kit workflow: Use 07_speckit-handoff.md as input to
/speckit.constitution - Discovery complete → Proceed to specification phase
Version History
- 2.0.0 (2026-01-07): Flat architecture (1 SKILL.md), cross-agent portability, 100% schema validation
- 1.1.0 (2026-01-06): Enhanced enforcement, automation workflow
- 1.0.0 (2026-01-05): Initial release with 8 sub-skills
Support & References
- Methodologies:
shared-references/methodologies.md - Glossary:
shared-references/glossary.md - Lite Workflow:
shared-references/workflows/lite-mode.md - Full Workflow:
shared-references/workflows/full-mode.md - Schemas:
schemas/*.schema.json - Templates:
templates/*.md