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

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:

bash

# 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:

bash

# 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:

bash

python3 scripts/validate.py <output-dir>

Expected Output:

code

✅ 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