Discovery Pack

Governance, Validation & Specification for AI Agents

"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
• Key Capabilities
• Operational Workflows
• Quick Start
• Artifact Reference
• Automation & Governance
• Installation
• 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 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:

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.

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.

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.

• Claude Code
• GitHub Copilot CLI
• VS Code (Agent Mode)
• Cursor

👉 Read the Installation Guide

---

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

---

Contributing

We are building the standard for Agentic Governance.

• Found a bug? Open an Issue.
• New methodology? Submit a PR.

See CONTRIBUTING.md for code of conduct and development standards.

---

• Spec-Kit Integration: Use 07_speckit-handoff.md output with GitHub Spec-Kit
• Methodologies: See shared-references/methodologies.md for detailed guidance
• Maintained by: nsalvacao
• License: MIT