---
slug: "discovery-pack"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/nsalvacao/discovery-pack@main/README.md"
repo: "https://github.com/nsalvacao/discovery-pack"
source_file: "README.md"
branch: "main"
---
# Discovery Pack
**Governance, Validation & Specification for AI Agents**

[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](CHANGELOG.md)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Build](https://img.shields.io/badge/build-passing-brightgreen.svg)](scripts/ci-validate.sh)
[![Compliance](https://img.shields.io/badge/schema%20compliance-100%25-success.svg)](skill/discovery-pack/schemas/)
[![Platform](https://img.shields.io/badge/platform-agnostic-orange.svg)](INSTALLATION.md)

> **"Ambiguity is the enemy of delivery."**
> 
> Discovery Pack creates a standardized, governed bridge between product vision and engineering implementation. It orchestrates AI agents to rigorosuly validate assumptions, enforce architectural standards, and generate implementation-ready specifications.

---

## 📚 Table of Contents

- [Overview](#overview)
- [Key Capabilities](#key-capabilities)
- [Operational Workflows](#operational-workflows)
- [Quick Start](#quick-start)
- [Artifact Reference](#artifact-reference)
- [Automation & Governance](#automation--governance)
- [Installation](#installation)
- [Contributing](#contributing)

---

## Overview

Discovery Pack is not just a collection of prompts; it is a complete **Governance System** designed for the agentic era. By combining proven methodologies (JTBD, DDD, ADR) with rigid schema validation and Python-based automation, it ensures that every specification generated by your AI agent is:

1.  **Valid**: Structurally correct according to JSON Schemas.
2.  **Auditable**: Traceable decisions and assumption logs.
3.  **Actionable**: Directly consumable by engineering teams and tools like `spec-kit`.

---

## Key Capabilities

### 🛡️ Risk Mitigation Engine
*   **Assumption Extraction**: Automatically scans discovery artifacts for `[ASSUMPTION]` and `[HYPOTHESIS]` tags to generate a prioritized risk register (`04_assumptions-unknowns.md`).
*   **Epistemic Tagging**: Enforces clear distinction between `[FACT]` (verified data) and `[CONSTRAINT]` (non-negotiable requirements).

### 🚦 Automated Gate Detection
*   **Logic Gates**: Python scripts analyze artifacts for logical fallacies (e.g., "Gate 1: Equivalent Options" detects when architectural choices lack meaningful trade-offs).
*   **Validation Checks**: Ensures validation plans contain quantitative success criteria, preventing "vanity metrics".

### 🏛️ Enterprise Compliance
*   **Schema Enforcement**: Every artifact (Problem Frame, Domain Model, etc.) is validated against strict JSON Schemas (Draft 07).
*   **Architectural Decision Records (ADR)**: Mandatory immutable logging of all structural decisions (`06_decision-log.md`).

---

## Operational Workflows

Choose the workflow rigor that matches your project's risk profile.

### 🔵 Lite Mode (Rapid Prototyping)
**Target**: Internal tools, POCs, low-risk features.
**Time**: 15-30 mins.

1.  **Problem Frame**: Define users and JTBD.
2.  **Option Space**: Quick trade-off analysis of approaches.
3.  **Handoff**: Generate Spec-Kit compatible output.

### 🟣 Full Mode (Enterprise Grade)
**Target**: Production systems, regulated domains, high-risk architecture.
**Time**: 1-2 hours.

1.  **Foundation**: Problem Frame + NFR Constraints.
2.  **Modeling**: Domain-Driven Design (Entities, Events).
3.  **Risk Management**: Auto-extraction of Assumptions + Validation Plan.
4.  **Governance**: Decision Log (ADR) + Logic Gate checks.
5.  **Handoff**: Validated Spec-Kit output.

---

## Quick Start

### 1. Install
[See detailed installation guide](https://github.com/nsalvacao/discovery-pack/blob/HEAD/INSTALLATION.md) for Claude, Copilot, and generic agent setup.

### 2. Initiate
Tell your agent:
> "Run discovery for a [Project Name] in [lite/full] mode."

### 3. Interact
The agent will guide you through the process, generating artifacts in:
`docs/discovery/YYYY-MM-DD-project-slug/`

**Example Interaction:**
```text
User: "I need a service to rate-limit API requests. Run discovery in full mode."

Agent: "Initiating Full Discovery for 'api-rate-limiter'.
        Creating: docs/discovery/2026-01-07-api-rate-limiter/
        
        Phase 1: Problem Framing (JTBD)
        Loaded template: 00_problem-frame.md
        
        Question: Who represents the primary security threat? Is it malicious bots or accidental overuse?"
```

---

## Artifact Reference

The system produces the following standardized artifacts:

| ID | Artifact | Methodology | Automation | Purpose |
|----|----------|-------------|------------|---------|
| `00` | **Problem Frame** | JTBD, PR/FAQ | Schema Validated | Defines user struggles and success metrics. |
| `01` | **Constraints** | NFRs | - | Security, compliance, and performance boundaries. |
| `02` | **Domain Model** | DDD | - | Ubiquitous language, entities, and bounded contexts. |
| `03` | **Option Space** | Trade-offs | Gate Check | Comparison of architectural approaches. |
| `04` | **Assumptions** | Epistemology | **Auto-Generated** | Centralized register of "Known Unknowns". |
| `05` | **Validation Plan** | Lean Startup | Gate Check | Experiments to falsify critical assumptions. |
| `06` | **Decision Log** | ADR | - | Immutable record of architectural choices. |
| `07` | **Handoff** | Spec-Kit | Validated | Input for specification and implementation. |

---

## Automation & Governance

The `scripts/` directory contains the engine that powers the governance model.

### `validate.py`
Enforces JSON Schema compliance for all markdown frontmatter.
```bash
python3 scripts/validate.py docs/discovery/my-project/
# Output: ✅ 00_problem-frame.md passed schema validation.
```

### `extract_assumptions.py`
Parses semantic tags (`[ASSUMPTION]`, `[CONSTRAINT]`) from narrative text to populate the Assumption Register.
```bash
python3 scripts/extract_assumptions.py docs/discovery/my-project/
# Output: 📊 Found 12 assumptions. Priority 'Critical' assigned to 3 constraints.
```

### `gate_detector.py`
Runs heuristic checks on project logic.
*   *Check*: Are options too similar in score?
*   *Check*: Do validation experiments lack pass/fail criteria?
*   *Check*: Are there contradictory assumptions?

---

## Installation

Discovery Pack is designed to be **Platform Agnostic**. It runs on any agent that supports the Agent Skills specification or can execute local scripts.

- [x] **Claude Code**
- [x] **GitHub Copilot CLI**
- [x] **VS Code (Agent Mode)**
- [x] **Cursor**

👉 **[Read the Installation Guide](https://github.com/nsalvacao/discovery-pack/blob/HEAD/INSTALLATION.md)**

---

## Integration with Spec-Kit

Discovery Pack generates spec-kit compatible outputs:

```
1. Run discovery-run → Generates 07_speckit-handoff.md
2. Review handoff artifact
3. Copy constitution section → /speckit.constitution
4. Copy specify section → /speckit.specify
5. Continue spec-kit workflow
```

Learn more: [GitHub Spec-Kit](https://github.com/github/spec-kit)

---

## Contributing

We are building the standard for Agentic Governance.
- **Found a bug?** Open an Issue.
- **New methodology?** Submit a PR.

See [CONTRIBUTING.md](https://github.com/nsalvacao/discovery-pack/blob/HEAD/CONTRIBUTING.md) for code of conduct and development standards.

---
- **Spec-Kit Integration**: Use `07_speckit-handoff.md` output with [GitHub Spec-Kit](https://github.com/github/spec-kit)
- **Methodologies**: See `shared-references/methodologies.md` for detailed guidance
- **Maintained by:** [nsalvacao](https://github.com/nsalvacao)
- **License:** [MIT](https://github.com/nsalvacao/discovery-pack/tree/HEAD/LICENSE)