🧩 Spec Extraction Workflow

[Alan-Jowett]

🧩 Spec Extraction Workflow

A PromptKit workflow to bootstrap any repository with clean, human‑verified requirements, design, and validation specs.

This issue proposes a new PromptKit workflow:
a Spec Extraction Workflow that analyzes an existing repository, extracts its semantic structure, collaborates with the user to clarify intent, and produces a clean requirements/design/validation baseline before handing the repo off to the Engineering Workflow.

This becomes the “bootstrap phase” for any project that wants to adopt PromptKit’s structured engineering lifecycle.

---

🎯 Goal

Create a PromptKit workflow that can be run on any repository to:

1. Analyze existing code, docs, issues, and tests
2. Extract draft requirements, design, and validation specs
3. Collaborate with the user to clarify ambiguous or missing intent
4. Audit the extracted specs for internal consistency
5. Produce a clean semantic baseline (requirements.md, design.md, validation.md)
6. Generate a PR containing the extracted and verified specs
7. Prepare the repo for future evolution using the Engineering Workflow

This workflow must include human‑in‑the‑loop clarification, since many requirements cannot be inferred solely from code or documentation.

---

🧩 Workflow Phases

1. Repository Analysis

The workflow scans:

• source code
• documentation
• issues
• tests
• architecture notes

It produces draft:

• requirements
• design
• validation rules

These drafts should be explicit about uncertainty, assumptions, and inferred intent.

---

2. Human Clarification Loop

PromptKit iteratively asks the user to confirm or correct extracted items:

• “Is this requirement correct?”
• “Is this behavior intentional or legacy?”
• “Should this constraint be preserved?”
• “Is this a bug or a feature?”
• “What’s missing from the current design?”

This loop continues until requirements are crisp, atomic, and testable.

---

3. Design Extraction

Based on the confirmed requirements, PromptKit generates a design spec describing:

• architecture
• components
• data flows
• constraints
• invariants
• interfaces

---

4. Validation Extraction

PromptKit generates a validation spec containing:

• testable invariants
• acceptance criteria
• behavioral constraints
• negative cases
• cross‑component consistency rules

---

5. Audit Phase

The workflow audits:

• requirements ↔ design alignment
• design ↔ validation alignment
• validation ↔ existing code alignment

It emits:

• drift reports
• missing invariants
• contradictions
• unclear or ambiguous sections

---

6. Human Approval

The user reviews the deltas for:

• requirements
• design
• validation
• audit findings

PromptKit iterates until the user approves the semantic baseline.

---

7. PR Generation

The workflow produces a PR containing:

• requirements.md
• design.md
• validation.md
• audit report
• summary of extracted insights
• notes on assumptions and unresolved ambiguities

This PR becomes the semantic foundation for the repo.

---

📦 Deliverables

• spec-extraction-workflow.md workflow definition
• Orchestrator persona
• Requirements extraction component
• Design extraction component
• Validation extraction component
• Audit component
• Human‑in‑the‑loop clarification protocol
• PR generation component
• Example usage on a sample repo

---

🧭 Notes

This workflow is the first half of a two‑workflow model:

1. Spec Extraction Workflow (bootstrap phase)
2. Engineering Workflow (ongoing evolution)

Together, they form a complete, multi‑domain engineering lifecycle that can be applied to software, firmware, electrical engineering, mechanical design, and more.

This feature will allow PromptKit to scale across all of Alan’s repos and any future project that needs a clean semantic foundation.

[Alan-Jowett]

Analysis: Existing Coverage and Net-New Work

Heavy reuse potential

Most of the individual phases map directly to existing PromptKit components:

Issue Phase	Existing Component(s)
1. Repository Analysis	reverse-engineer-requirements template + requirements-from-implementation protocol
3. Design Extraction	author-design-doc template
4. Validation Extraction	author-validation-plan template
5. Audit	audit-traceability + audit-code-compliance + audit-test-compliance templates
7. PR Generation	Git operations (same as engineering-workflow Phase 8)

What's actually new

1. One orchestration template (spec-extraction-workflow.md) -- interactive, multi-phase, with the clarification loop as its core differentiator
2. Possibly one new protocol for structured code-to-spec extraction reasoning (the existing requirements-from-implementation protocol may suffice, but a broader protocol covering code + docs + issues + tests as input sources could add value)

Deliverables list refinement

• Orchestrator persona: Not needed -- use configurable personas (same pattern as engineering-workflow). reverse-engineer for extraction, software-architect for design, specification-analyst for audit.
• PR generation component: Not a PromptKit component -- just git operations described in the orchestration template.
• Output formats: Existing requirements-doc, design-doc, validation-plan, and investigation-report formats cover all outputs. No new format needed.

Architecture suggestion

This workflow is the bootstrap complement to the engineering-workflow (#115):

• spec-extraction-workflow = "I have a repo with no specs -- give me a semantic baseline"
• engineering-workflow = "I have specs -- propagate a change through the stack"

The orchestration template should produce artifacts in the same formats that engineering-workflow consumes, so users can seamlessly transition from bootstrap to evolution.