mia-code 0.2.0 → 0.3.0

package/rispecs/pde.rispecs.md

@@ -0,0 +1,399 @@
+# mia-code PDE Integration Specification
+
+> RISE Framework Specification v1.0
+> Document: mia-code/rispecs/pde.rispecs.md
+> Status: DRAFT - Future Enhancement
+
+## Creative Intent
+
+mia-code enables developers to create comprehensive multi-intent workflows from complex prompts through the Prompt Decomposition Engine (PDE). Users achieve complete fulfillment of compound requests by having the system decompose, orchestrate, and execute all implicit and explicit intentions systematically.
+
+## Structural Tension Analysis
+
+**Current Structural Reality:**
+- Complex user prompts often contain multiple implicit intentions
+- Agents may ignore secondary intentions or nested requirements
+- Multi-step progress tracking is manual and error-prone
+- Context loss occurs between sequential actions
+- No structured decomposition exists before execution
+
+**Desired Structural State:**
+- Every complex prompt decomposes into structured intent graph
+- All explicit and implicit intentions are captured and classified
+- Dependencies between intents determine execution order
+- Progress checkpoints enable recovery and visibility
+- Parallel execution where dependencies permit
+
+## PDE Architecture Overview
+
+### Five-Layer Decomposition Pipeline
+
+```
+Layer 1: Intent Extraction & Classification
+    ↓ Explicit actions, implicit requirements, type classification
+Layer 2: Dependency Graph Construction
+    ↓ Prerequisites, blockers, enablers, data flow
+Layer 3: Direction Assignment (Medicine Wheel)
+    ↓ EAST/SOUTH/WEST/NORTH epistemological mapping
+Layer 4: Workflow Template Generation
+    ↓ Parallel/sequential/conditional stages
+Layer 5: Execution Plan with Checkpoints
+    ↓ Agent commands, success criteria, fallbacks
+```
+
+### Academic Foundation
+
+PDE draws from established research:
+
+- **Decomposed Prompting (DecomP):** Modular sub-task decomposition via prompting [^1_12][^1_13]
+- **Chain-of-Thought (CoT):** Step-by-step reasoning traces [^1_10][^1_11]
+- **ReAct Pattern:** Interleaved reasoning and action [^1_15][^1_16]
+- **Hierarchical Task Networks:** Recursive goal decomposition [^1_17][^1_18]
+- **Multi-Agent Orchestration:** Coordination with guardrails [^1_28]
+
+## Layer Specifications
+
+### Layer 1: Intent Extraction & Classification
+
+**Purpose:** Parse raw prompt into structured intent objects.
+
+**Decomposition Chain:**
+
+```typescript
+const intentExtractionChain = {
+  // Step 1: Explicit Action Identification
+  step1: {
+    prompt: `Analyze this user request and identify ALL explicit action verbs:
+    "${userPrompt}"
+    
+    For each action, extract:
+    - Action verb (create, update, analyze, design, etc.)
+    - Target object (file, system, component, etc.)
+    - Implicit parameters or constraints
+    
+    Output as JSON array of {action, target, constraints}`
+  },
+  
+  // Step 2: Implicit Intent Discovery
+  step2: {
+    prompt: `Given these explicit actions: ${step1.result}
+    
+    Now identify IMPLICIT requirements in the original request:
+    "${userPrompt}"
+    
+    Look for:
+    - "which I assume" → assumptions requiring validation
+    - "you will" → expectations without explicit instruction
+    - "somehow" → uncertainty markers
+    - "I expect" → unstated success criteria
+    - Dependencies on external context
+    
+    Output as JSON array of {implicitIntent, triggerPhrase, priority}`
+  },
+  
+  // Step 3: Intent Classification
+  step3: {
+    prompt: `Classify each intent by type:
+    
+    Categories:
+    - CREATION (generate new artifacts)
+    - MODIFICATION (update existing)
+    - ANALYSIS (investigate/understand)
+    - VALIDATION (verify/test)
+    - INTEGRATION (connect systems)
+    - COMMUNICATION (notifications/reports)
+    
+    Output as JSON: {intentId, type, confidence}`
+  }
+};
+```
+
+**Output:** `ClassifiedIntent[]` with explicit/implicit flag and type
+
+### Layer 2: Dependency Graph Construction
+
+**Purpose:** Map inter-intent dependencies for execution ordering.
+
+**Analysis Prompt:**
+
+```typescript
+const dependencyAnalysisChain = {
+  step1: {
+    prompt: `Given these classified intents:
+    ${JSON.stringify(classifiedIntents)}
+    
+    Build a dependency graph:
+    
+    For each intent, determine:
+    1. Prerequisites (which intents MUST complete first?)
+    2. Blockers (which intents CANNOT run in parallel?)
+    3. Enablers (which intents enable optional paths?)
+    4. Data flow (what outputs become inputs?)
+    
+    Use directed graph notation: A -> B means B depends on A
+    Use parallel notation: [A, B] means can run simultaneously
+    
+    Output as adjacency list JSON`
+  }
+};
+```
+
+**Techniques:**
+- Tree-of-Thoughts (ToT) for multiple dependency interpretations
+- Least-to-Most prompting for incremental complexity
+- Cycle detection with resolution strategies
+
+**Output:** `DependencyGraph` with nodes, edges, parallelization groups
+
+### Layer 3: Medicine Wheel Direction Assignment
+
+**Purpose:** Map intents to epistemological framework for ceremony-aware processing.
+
+**Direction Criteria:**
+
+| Direction | Mode | Ceremony Type | Characteristics |
+|-----------|------|---------------|-----------------|
+| EAST | Vision/Inquiry | vision_inquiry | Exploratory, question-forming, initial research |
+| SOUTH | Growth/Learning | wave_counting | Data gathering, skill building, analysis |
+| WEST | Integration/Validation | talking_circles | Testing, reflection, refinement |
+| NORTH | Wisdom/Action | elder_council | Implementation, deployment, finalization |
+
+**Assignment Prompt:**
+
+```typescript
+const medicineWheelMapping = {
+  prompt: `Analyze each intent and assign Medicine Wheel direction:
+  
+  Intents: ${JSON.stringify(intents)}
+  
+  For each intent, provide:
+  - Primary direction (main epistemological mode)
+  - Secondary direction (supporting mode, if applicable)
+  - Ceremony type
+  - Rationale (why this direction fits)
+  
+  Output as JSON array`
+};
+```
+
+**Output:** `DirectionAssignment[]` with primary/secondary directions and ceremony
+
+### Layer 4: Workflow Template Generation
+
+**Purpose:** Generate executable workflow structure from dependency graph and directions.
+
+**Stage Types:**
+- `parallel`: Independent intents execute concurrently
+- `sequential`: Dependent intents execute in order
+- `conditional`: Validation gates control branching
+
+**Template Structure:**
+
+```typescript
+interface WorkflowTemplate {
+  workflowId: string;
+  stages: Array<{
+    stageId: string;
+    type: "parallel" | "sequential" | "conditional";
+    direction: "east" | "south" | "west" | "north";
+    tasks: IntentTask[];
+    checkpointAfter: boolean;
+  }>;
+}
+```
+
+**Output:** `WorkflowTemplate` with staged execution plan
+
+### Layer 5: Execution Plan with Checkpoints
+
+**Purpose:** Convert workflow to agent-executable commands with recovery support.
+
+**Task Specification:**
+
+```typescript
+interface ExecutionTask {
+  taskId: string;
+  description: string;
+  command: string;                // Agent CLI command
+  inputs: string[];               // Files, context keys
+  expectedOutputs: string[];      // Artifact paths
+  successCriteria: string;        // How to verify completion
+  fallbackStrategy: string;       // Recovery on failure
+  checkpointMessage: string;      // Progress report
+}
+```
+
+**Execution Plan Output:**
+
+```markdown
+## Execution Plan
+
+### Stage 1 (EAST - Vision Inquiry): Requirements Analysis
+- [ ] Extract JWT requirements from request
+  - Command: `mia-code prompt "analyze JWT requirements..."`
+  - Success: JWT spec object exists
+  - Checkpoint: "Completed 1/4: Requirements analyzed"
+
+### Stage 2 (SOUTH - Wave Counting): Implementation
+[Parallel execution possible]
+- [ ] Create auth service with JWT
+- [ ] Design database schema
+- [ ] Setup test infrastructure
+
+### Stage 3 (WEST - Talking Circles): Validation
+- [ ] Run test suite
+- [ ] Security audit
+
+### Stage 4 (NORTH - Elder Council): Deployment
+- [ ] Deploy to staging
+- [ ] Generate deployment report
+```
+
+## CLI Integration
+
+### PDE-Enabled Commands
+
+```bash
+# Decompose and preview (don't execute)
+mia-code decompose "Create user auth with JWT, PostgreSQL, tests, deploy"
+
+# Execute with PDE enabled
+mia-code chat --pde "Complex multi-intent prompt..."
+
+# Resume from checkpoint
+mia-code resume --checkpoint stage-2-task-3
+```
+
+### Output Format (Decompose Preview)
+
+```
+📋 Decomposed Workflow:
+
+Stage 1 (EAST - Vision Inquiry): Requirements Analysis
+  - [ ] Extract JWT requirements
+  - [ ] Identify PostgreSQL schema needs
+
+Stage 2 (SOUTH - Wave Counting): Implementation
+  [Parallel]
+  - [ ] Create auth service
+  - [ ] Design database schema
+
+Stage 3 (WEST - Talking Circles): Validation
+  - [ ] Run test suite
+  - [ ] Security audit
+
+Stage 4 (NORTH - Elder Council): Deployment
+  - [ ] Deploy to staging
+
+Proceed with execution? [y/N]
+```
+
+## Data Structures
+
+### DecomposedPrompt
+
+```typescript
+interface DecomposedPrompt {
+  originalPrompt: string;
+  intents: ClassifiedIntent[];
+  dependencyGraph: DependencyGraph;
+  directionAssignments: DirectionAssignment[];
+  workflow: WorkflowTemplate;
+  executionPlan: ExecutionPlan;
+}
+```
+
+### ClassifiedIntent
+
+```typescript
+interface ClassifiedIntent {
+  intentId: string;
+  action: string;
+  target: string;
+  type: "CREATION" | "MODIFICATION" | "ANALYSIS" | "VALIDATION" | "INTEGRATION" | "COMMUNICATION";
+  isImplicit: boolean;
+  confidence: number;
+  constraints: string[];
+}
+```
+
+### ProgressStatus
+
+```typescript
+interface ProgressStatus {
+  currentStage: number;
+  totalStages: number;
+  currentTask: number;
+  totalTasks: number;
+  completedTasks: string[];
+  failedTasks: string[];
+  checkpoints: CheckpointRecord[];
+}
+```
+
+## Creative Advancement Scenarios
+
+### Creative Advancement Scenario: Complex Project Setup
+
+**Desired Outcome:** Developer creates full project scaffolding from single prompt
+
+**User Prompt:** "Create a TypeScript Express API with JWT auth, PostgreSQL connection, Prisma ORM, unit tests, Docker setup, and CI pipeline"
+
+**Natural Progression:**
+1. PDE Layer 1 extracts 6 explicit intents
+2. Layer 2 identifies dependencies (Prisma needs PostgreSQL schema first)
+3. Layer 3 assigns directions (Docker/CI = NORTH, Tests = WEST)
+4. Layer 4 generates 4-stage workflow with parallel blocks
+5. Layer 5 produces checkpointed execution plan
+6. User previews and confirms
+7. Execution proceeds with progress visibility
+
+**Achieved Outcome:** Complete project setup with all components, tracked progress, failure recovery
+
+### Creative Advancement Scenario: Failure Recovery
+
+**Desired Outcome:** Developer recovers from mid-workflow failure
+
+**Current Structural Reality:** Stage 2 task 3 failed, partial progress exists
+
+**Natural Progression:**
+1. User invokes `mia-code resume --checkpoint stage-2-task-3`
+2. System loads checkpoint state
+3. Fallback strategy consulted
+4. Failed task retried or alternative executed
+5. Workflow continues from recovery point
+
+**Achieved Outcome:** Workflow completes without restarting from beginning
+
+## Advancing Patterns
+
+1. **Intent Completeness:** All explicit and implicit intentions captured
+2. **Parallel Optimization:** Independent tasks execute concurrently
+3. **Ceremony Integration:** Epistemological mapping guides processing mode
+4. **Checkpoint Recovery:** Progress persists for failure resilience
+5. **Preview Control:** User confirms plan before execution
+
+## Academic References
+
+[^1_10]: Wei et al., "Chain of Thought Prompting Elicits Reasoning in Large Language Models"
+[^1_11]: Kojima et al., "Large Language Models are Zero-Shot Reasoners"
+[^1_12]: Khot et al., "Decomposed Prompting: A Modular Approach For Solving Complex Tasks"
+[^1_13]: Zhou et al., "Least-to-Most Prompting Enables Complex Reasoning"
+[^1_15]: Yao et al., "ReAct: Synergizing Reasoning and Acting in Language Models"
+[^1_16]: Shinn et al., "Reflexion: Language Agents with Verbal Reinforcement Learning"
+[^1_17]: Ghallab et al., "Automated Planning: Theory and Practice" (HTN)
+[^1_18]: Nau et al., "SHOP2: An HTN Planning System"
+[^1_28]: Gupta et al., "MARCO: Multi-Agent Real-time Chat Orchestration"
+
+## Implementation Status
+
+**Current:** Not implemented  
+**Priority:** Future enhancement  
+**Dependencies:** Core mia-code functionality stable  
+**Effort Estimate:** Multi-phase implementation
+
+## Implementation Reference
+
+- **Literature Index:** `/src/IAIP/prototypes/artefacts/PDE-generalization--*/INDEX.md`
+- **Research Content:** `/src/IAIP/prototypes/artefacts/PDE-generalization--*/CONTENT.md`
+- **Source Papers:** `/src/IAIP/prototypes/artefacts/PDE-generalization--*/sources/`