mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-06 16:31:12 +08:00
Add comprehensive documentation for Numerical Analysis Workflow
- Introduced agent instruction template for task assignments in numerical analysis. - Defined CSV schema for tasks, including input, computed, and output columns. - Specified analysis dimensions across six phases of the workflow. - Established phase topology for the diamond deep tree structure of the workflow. - Outlined quality standards for assessing analysis reports, including criteria and quality gates.
This commit is contained in:
catlog22
@@ -1,630 +0,0 @@
|
||||
---
|
||||
name: numerical-analysis-workflow
|
||||
description: Global-to-local numerical computation project analysis workflow. Decomposes analysis into 6-phase diamond topology (Global → Theory → Algorithm → Module → Local → Integration) with parallel analysis tracks per phase, cross-phase context propagation, and LaTeX formula support. Produces comprehensive analysis documents covering mathematical foundations, numerical stability, convergence, error bounds, and software architecture.
|
||||
argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"project path or description\""
|
||||
allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-confirm track decomposition, skip interactive validation, use defaults.
|
||||
|
||||
# Numerical Analysis Workflow
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
$numerical-analysis-workflow "Analyze the FEM solver in src/solver/"
|
||||
$numerical-analysis-workflow -c 3 "Analyze CFD simulation pipeline for numerical stability"
|
||||
$numerical-analysis-workflow -y "Full analysis of PDE discretization in src/pde/"
|
||||
$numerical-analysis-workflow --continue "nadw-fem-solver-20260304"
|
||||
```
|
||||
|
||||
**Flags**:
|
||||
- `-y, --yes`: Skip all confirmations (auto mode)
|
||||
- `-c, --concurrency N`: Max concurrent agents within each wave (default: 3)
|
||||
- `--continue`: Resume existing session
|
||||
|
||||
**Output Directory**: `.workflow/.csv-wave/{session-id}/`
|
||||
**Core Output**: `tasks.csv` (master state) + `results.csv` (final) + `discoveries.ndjson` (shared exploration) + `context.md` (human-readable report)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Six-phase diamond topology for analyzing numerical computation software projects. Each phase represents a wave; within each wave, 2-5 parallel analysis tracks produce focused documents. Context packages propagate cumulatively between waves, enabling perspective reuse — theory informs algorithm design, algorithm informs implementation, all converge at integration.
|
||||
|
||||
**Core workflow**: Survey → Theorize → Design → Analyze Modules → Optimize Locally → Integrate & Validate
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ NUMERICAL ANALYSIS DIAMOND WORKFLOW (NADW) │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Wave 1: Global Survey [3 tracks] │
|
||||
│ ├─ T1.1 Problem Domain Survey (math models, governing equations) │
|
||||
│ ├─ T1.2 Software Architecture Overview (modules, data flow) │
|
||||
│ └─ T1.3 Validation Strategy (benchmarks, KPIs, acceptance) │
|
||||
│ ↓ Context Package P1 │
|
||||
│ │
|
||||
│ Wave 2: Theoretical Foundations [3 tracks] │
|
||||
│ ├─ T2.1 Mathematical Formulation (LaTeX derivation, weak forms) │
|
||||
│ ├─ T2.2 Convergence Analysis (error bounds, convergence order) │
|
||||
│ └─ T2.3 Complexity Analysis (time/space Big-O, operation counts) │
|
||||
│ ↓ Context Package P1+P2 │
|
||||
│ │
|
||||
│ Wave 3: Algorithm Design & Stability [3 tracks] │
|
||||
│ ├─ T3.1 Algorithm Specification (method selection, pseudocode) │
|
||||
│ ├─ T3.2 Numerical Stability Report (condition numbers, error prop) │
|
||||
│ └─ T3.3 Performance Model (FLOPS, memory bandwidth, parallelism) │
|
||||
│ ↓ Context Package P1+P2+P3 │
|
||||
│ │
|
||||
│ Wave 4: Module Implementation [3 tracks] │
|
||||
│ ├─ T4.1 Core Module Analysis (algorithm-code mapping) │
|
||||
│ ├─ T4.2 Data Structure Review (sparse formats, memory layout) │
|
||||
│ └─ T4.3 API Contract Analysis (interfaces, error handling) │
|
||||
│ ↓ Context Package P1-P4 │
|
||||
│ │
|
||||
│ Wave 5: Local Function-Level [3 tracks] │
|
||||
│ ├─ T5.1 Optimization Report (hotspots, vectorization, cache) │
|
||||
│ ├─ T5.2 Edge Case Analysis (singularities, overflow, degeneracy) │
|
||||
│ └─ T5.3 Precision Audit (catastrophic cancellation, accumulation) │
|
||||
│ ↓ Context Package P1-P5 │
|
||||
│ │
|
||||
│ Wave 6: Integration & QA [3 tracks] │
|
||||
│ ├─ T6.1 Integration Test Plan (end-to-end, regression, benchmark) │
|
||||
│ ├─ T6.2 Benchmark Results (actual vs theoretical performance) │
|
||||
│ └─ T6.3 Final QA Report (all-phase synthesis, risk matrix, roadmap) │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Diamond Topology** (Wide → Deep → Wide):
|
||||
```
|
||||
Wave 1: [T1.1] [T1.2] [T1.3] ← Global扇出
|
||||
Wave 2: [T2.1] [T2.2] [T2.3] ← Theory深入
|
||||
Wave 3: [T3.1] [T3.2] [T3.3] ← Algorithm桥接
|
||||
Wave 4: [T4.1] [T4.2] [T4.3] ← Module聚焦
|
||||
Wave 5: [T5.1] [T5.2] [T5.3] ← Local最细
|
||||
Wave 6: [T6.1] [T6.2] [T6.3] ← Integration汇聚
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CSV Schema
|
||||
|
||||
### tasks.csv (Master State)
|
||||
|
||||
```csv
|
||||
id,title,description,track_role,analysis_dimension,formula_refs,precision_req,scope,deps,context_from,wave,status,findings,severity_distribution,latex_formulas,doc_path,error
|
||||
"T1.1","Problem Domain Survey","Survey governing equations and mathematical models for the numerical computation project. Identify PDE types, boundary conditions, conservation laws.","Problem_Domain_Analyst","domain_modeling","","","src/**","","","1","","","","","",""
|
||||
"T2.1","Mathematical Formulation","Derive precise mathematical formulations using LaTeX. Transform governing equations into weak forms suitable for discretization.","Mathematician","formula_derivation","T1.1:governing_eqs","","src/**","T1.1","T1.1","2","","","","","",""
|
||||
"T3.1","Algorithm Specification","Select numerical methods and design algorithms based on theoretical analysis. Produce pseudocode for core computational kernels.","Algorithm_Designer","method_selection","T2.1:weak_forms;T2.2:convergence_conds","double","src/solver/**","T2.1","T2.1;T2.2;T2.3","3","","","","","",""
|
||||
```
|
||||
|
||||
**Columns**:
|
||||
|
||||
| Column | Phase | Description |
|
||||
|--------|-------|-------------|
|
||||
| `id` | Input | Unique task identifier (T{wave}.{track}) |
|
||||
| `title` | Input | Short task title |
|
||||
| `description` | Input | Detailed task description (self-contained for agent) |
|
||||
| `track_role` | Input | Analysis role name (e.g., Mathematician, Stability_Analyst) |
|
||||
| `analysis_dimension` | Input | Analysis focus area (domain_modeling, formula_derivation, stability, etc.) |
|
||||
| `formula_refs` | Input | Semicolon-separated references to formulas from earlier tasks (TaskID:formula_name) |
|
||||
| `precision_req` | Input | Required floating-point precision (float/double/quad/adaptive) |
|
||||
| `scope` | Input | File/directory scope for analysis (glob pattern) |
|
||||
| `deps` | Input | Semicolon-separated dependency task IDs |
|
||||
| `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
|
||||
| `wave` | Computed | Wave number (1-6, from phase assignment) |
|
||||
| `status` | Output | `pending` → `completed` / `failed` / `skipped` |
|
||||
| `findings` | Output | Key discoveries and conclusions (max 500 chars) |
|
||||
| `severity_distribution` | Output | Issue counts: Critical/High/Medium/Low |
|
||||
| `latex_formulas` | Output | Key LaTeX formulas discovered or derived (semicolon-separated) |
|
||||
| `doc_path` | Output | Path to generated analysis document |
|
||||
| `error` | Output | Error message if failed |
|
||||
|
||||
### Per-Wave CSV (Temporary)
|
||||
|
||||
Each wave generates a temporary `wave-{N}.csv` with extra `prev_context` column.
|
||||
|
||||
---
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| File | Purpose | Lifecycle |
|
||||
|------|---------|-----------|
|
||||
| `tasks.csv` | Master state — all tasks with status/findings | Updated after each wave |
|
||||
| `wave-{N}.csv` | Per-wave input (temporary) | Created before wave, deleted after |
|
||||
| `results.csv` | Final export of all task results | Created in Phase 3 |
|
||||
| `discoveries.ndjson` | Shared exploration board across all agents | Append-only, carries across waves |
|
||||
| `context.md` | Human-readable execution report | Created in Phase 3 |
|
||||
| `docs/P{N}_*.md` | Per-track analysis documents | Created by each agent |
|
||||
|
||||
---
|
||||
|
||||
## Session Structure
|
||||
|
||||
```
|
||||
.workflow/.csv-wave/{session-id}/
|
||||
├── tasks.csv # Master state (updated per wave)
|
||||
├── results.csv # Final results export
|
||||
├── discoveries.ndjson # Shared discovery board (all agents)
|
||||
├── context.md # Human-readable report
|
||||
├── docs/ # Analysis documents per track
|
||||
│ ├── P1_Domain_Survey.md
|
||||
│ ├── P1_Architecture_Overview.md
|
||||
│ ├── P1_Validation_Strategy.md
|
||||
│ ├── P2_Mathematical_Formulation.md
|
||||
│ ├── P2_Convergence_Analysis.md
|
||||
│ ├── P2_Complexity_Analysis.md
|
||||
│ ├── P3_Algorithm_Specification.md
|
||||
│ ├── P3_Numerical_Stability_Report.md
|
||||
│ ├── P3_Performance_Model.md
|
||||
│ ├── P4_Module_Implementation_Analysis.md
|
||||
│ ├── P4_Data_Structure_Review.md
|
||||
│ ├── P4_API_Contract.md
|
||||
│ ├── P5_Optimization_Report.md
|
||||
│ ├── P5_Edge_Case_Analysis.md
|
||||
│ ├── P5_Precision_Audit.md
|
||||
│ ├── P6_Integration_Test_Plan.md
|
||||
│ ├── P6_Benchmark_Results.md
|
||||
│ └── P6_Final_QA_Report.md
|
||||
└── wave-{N}.csv # Temporary per-wave input (cleaned up)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation
|
||||
|
||||
### Session Initialization
|
||||
|
||||
```javascript
|
||||
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
|
||||
|
||||
// Parse flags
|
||||
const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
|
||||
const continueMode = $ARGUMENTS.includes('--continue')
|
||||
const concurrencyMatch = $ARGUMENTS.match(/(?:--concurrency|-c)\s+(\d+)/)
|
||||
const maxConcurrency = concurrencyMatch ? parseInt(concurrencyMatch[1]) : 3
|
||||
|
||||
// Clean requirement text
|
||||
const requirement = $ARGUMENTS
|
||||
.replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+/g, '')
|
||||
.trim()
|
||||
|
||||
const slug = requirement.toLowerCase()
|
||||
.replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
|
||||
.substring(0, 40)
|
||||
const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
|
||||
const sessionId = `nadw-${slug}-${dateStr}`
|
||||
const sessionFolder = `.workflow/.csv-wave/${sessionId}`
|
||||
|
||||
Bash(`mkdir -p ${sessionFolder}/docs`)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 1: Requirement → CSV (Decomposition)
|
||||
|
||||
**Objective**: Analyze the target project/requirement, decompose into 18 analysis tasks (6 waves × 3 tracks), compute wave assignments, generate tasks.csv.
|
||||
|
||||
**Decomposition Rules**:
|
||||
|
||||
| Wave | Phase Name | Track Roles | Analysis Focus |
|
||||
|------|-----------|-------------|----------------|
|
||||
| 1 | Global Survey | Problem_Domain_Analyst, Software_Architect, Validation_Strategist | Mathematical models, architecture, validation strategy |
|
||||
| 2 | Theoretical Foundations | Mathematician, Convergence_Analyst, Complexity_Analyst | Formula derivation, convergence proofs, complexity bounds |
|
||||
| 3 | Algorithm Design | Algorithm_Designer, Stability_Analyst, Performance_Modeler | Method selection, numerical stability, performance prediction |
|
||||
| 4 | Module Implementation | Module_Implementer, Data_Structure_Designer, Interface_Analyst | Code-algorithm mapping, data structures, API contracts |
|
||||
| 5 | Local Function-Level | Code_Optimizer, Edge_Case_Analyst, Precision_Auditor | Hotspot optimization, boundary handling, float precision |
|
||||
| 6 | Integration & QA | Integration_Tester, Benchmark_Engineer, QA_Auditor | End-to-end testing, benchmarks, final quality report |
|
||||
|
||||
**Dependency Structure** (Diamond Topology):
|
||||
|
||||
| Task | deps | context_from | Rationale |
|
||||
|------|------|-------------|-----------|
|
||||
| T1.* | (none) | (none) | Wave 1: independent, global survey |
|
||||
| T2.1 | T1.1 | T1.1 | Formalization needs governing equations |
|
||||
| T2.2 | T1.1 | T1.1 | Convergence analysis needs model identification |
|
||||
| T2.3 | T1.1;T1.2 | T1.1;T1.2 | Complexity needs both model and architecture |
|
||||
| T3.1 | T2.1 | T2.1;T2.2;T2.3 | Algorithm design needs all theory |
|
||||
| T3.2 | T2.1;T2.2 | T2.1;T2.2 | Stability needs formulas and convergence |
|
||||
| T3.3 | T2.3 | T1.2;T2.3 | Performance model needs architecture + complexity |
|
||||
| T4.* | T3.* | T1.*;T3.* | Module analysis needs global + algorithm context |
|
||||
| T5.* | T4.* | T3.*;T4.* | Local analysis needs algorithm + module context |
|
||||
| T6.* | T5.* | T1.*;T2.*;T3.*;T4.*;T5.* | Integration receives ALL context |
|
||||
|
||||
**Decomposition CLI Call**:
|
||||
|
||||
```javascript
|
||||
Bash({
|
||||
command: `ccw cli -p "PURPOSE: Decompose numerical computation project analysis into 18 tasks across 6 phases.
|
||||
TASK:
|
||||
• Analyze the project to identify: governing equations, numerical methods used, module structure
|
||||
• Generate 18 analysis tasks (3 per phase × 6 phases) following the NADW diamond topology
|
||||
• Each task must be self-contained with clear scope and analysis dimension
|
||||
• Assign track_role, analysis_dimension, formula_refs, precision_req, scope for each task
|
||||
• Set deps and context_from following the diamond dependency pattern
|
||||
MODE: analysis
|
||||
CONTEXT: @**/*
|
||||
EXPECTED: JSON with tasks array. Each task: {id, title, description, track_role, analysis_dimension, formula_refs, precision_req, scope, deps[], context_from[]}
|
||||
CONSTRAINTS: Exactly 6 waves, 3 tasks per wave. Wave 1=Global, Wave 2=Theory, Wave 3=Algorithm, Wave 4=Module, Wave 5=Local, Wave 6=Integration.
|
||||
|
||||
PROJECT TO ANALYZE: ${requirement}" --tool gemini --mode analysis --rule planning-breakdown-task-steps`,
|
||||
run_in_background: true
|
||||
})
|
||||
```
|
||||
|
||||
**Wave Computation**: Fixed 6-wave assignment per the diamond topology. Tasks within each wave are independent.
|
||||
|
||||
**CSV Generation**: Parse JSON response, validate 18 tasks with correct wave assignments, generate tasks.csv with proper escaping.
|
||||
|
||||
**User Validation**: Display task breakdown grouped by wave (skip if AUTO_YES):
|
||||
|
||||
```
|
||||
Wave 1 (Global Survey):
|
||||
T1.1 Problem Domain Survey → Problem_Domain_Analyst
|
||||
T1.2 Software Architecture Overview → Software_Architect
|
||||
T1.3 Validation Strategy → Validation_Strategist
|
||||
|
||||
Wave 2 (Theoretical Foundations):
|
||||
T2.1 Mathematical Formulation → Mathematician
|
||||
T2.2 Convergence Analysis → Convergence_Analyst
|
||||
T2.3 Complexity Analysis → Complexity_Analyst
|
||||
...
|
||||
```
|
||||
|
||||
**Success Criteria**:
|
||||
- tasks.csv created with 18 tasks, 6 waves, valid schema
|
||||
- No circular dependencies
|
||||
- Each task has track_role and analysis_dimension
|
||||
- User approved (or AUTO_YES)
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Wave Execution Engine
|
||||
|
||||
**Objective**: Execute analysis tasks wave-by-wave via spawn_agents_on_csv with cross-wave context propagation and cumulative context packages.
|
||||
|
||||
```javascript
|
||||
// Read master CSV
|
||||
const masterCsv = Read(`${sessionFolder}/tasks.csv`)
|
||||
const tasks = parseCsv(masterCsv)
|
||||
const maxWave = 6
|
||||
|
||||
for (let wave = 1; wave <= maxWave; wave++) {
|
||||
// 1. Filter tasks for this wave
|
||||
const waveTasks = tasks.filter(t => t.wave === wave && t.status === 'pending')
|
||||
|
||||
// 2. Skip tasks whose deps failed/skipped
|
||||
for (const task of waveTasks) {
|
||||
const depIds = task.deps.split(';').filter(Boolean)
|
||||
const depStatuses = depIds.map(id => tasks.find(t => t.id === id)?.status)
|
||||
if (depStatuses.some(s => s === 'failed' || s === 'skipped')) {
|
||||
task.status = 'skipped'
|
||||
task.error = `Dependency failed: ${depIds.filter((id, i) => ['failed','skipped'].includes(depStatuses[i])).join(', ')}`
|
||||
continue
|
||||
}
|
||||
}
|
||||
|
||||
const pendingTasks = waveTasks.filter(t => t.status === 'pending')
|
||||
if (pendingTasks.length === 0) continue
|
||||
|
||||
// 3. Build prev_context from context_from + master CSV findings
|
||||
for (const task of pendingTasks) {
|
||||
const contextIds = task.context_from.split(';').filter(Boolean)
|
||||
const prevFindings = contextIds.map(id => {
|
||||
const src = tasks.find(t => t.id === id)
|
||||
return src?.findings ? `[${src.id} ${src.title}]: ${src.findings}` : ''
|
||||
}).filter(Boolean).join('\n\n')
|
||||
|
||||
// Also include latex_formulas from context sources
|
||||
const prevFormulas = contextIds.map(id => {
|
||||
const src = tasks.find(t => t.id === id)
|
||||
return src?.latex_formulas ? `[${src.id} formulas]: ${src.latex_formulas}` : ''
|
||||
}).filter(Boolean).join('\n')
|
||||
|
||||
task.prev_context = prevFindings + (prevFormulas ? '\n\n--- Referenced Formulas ---\n' + prevFormulas : '')
|
||||
}
|
||||
|
||||
// 4. Write per-wave CSV
|
||||
Write(`${sessionFolder}/wave-${wave}.csv`, toCsv(pendingTasks))
|
||||
|
||||
// 5. Execute wave
|
||||
spawn_agents_on_csv({
|
||||
csv_path: `${sessionFolder}/wave-${wave}.csv`,
|
||||
id_column: "id",
|
||||
instruction: buildInstructionTemplate(sessionFolder, wave),
|
||||
max_concurrency: maxConcurrency,
|
||||
max_runtime_seconds: 900,
|
||||
output_csv_path: `${sessionFolder}/wave-${wave}-results.csv`,
|
||||
output_schema: {
|
||||
type: "object",
|
||||
properties: {
|
||||
id: { type: "string" },
|
||||
status: { type: "string", enum: ["completed", "failed"] },
|
||||
findings: { type: "string" },
|
||||
severity_distribution: { type: "string" },
|
||||
latex_formulas: { type: "string" },
|
||||
doc_path: { type: "string" },
|
||||
error: { type: "string" }
|
||||
},
|
||||
required: ["id", "status", "findings"]
|
||||
}
|
||||
})
|
||||
|
||||
// 6. Merge results into master CSV
|
||||
const waveResults = parseCsv(Read(`${sessionFolder}/wave-${wave}-results.csv`))
|
||||
for (const result of waveResults) {
|
||||
const masterTask = tasks.find(t => t.id === result.id)
|
||||
if (masterTask) {
|
||||
masterTask.status = result.status
|
||||
masterTask.findings = result.findings
|
||||
masterTask.severity_distribution = result.severity_distribution || ''
|
||||
masterTask.latex_formulas = result.latex_formulas || ''
|
||||
masterTask.doc_path = result.doc_path || ''
|
||||
masterTask.error = result.error || ''
|
||||
}
|
||||
}
|
||||
Write(`${sessionFolder}/tasks.csv`, toCsv(tasks))
|
||||
|
||||
// 7. Cleanup temp wave CSV
|
||||
Bash(`rm -f ${sessionFolder}/wave-${wave}.csv ${sessionFolder}/wave-${wave}-results.csv`)
|
||||
|
||||
// 8. Display wave summary
|
||||
const completed = waveResults.filter(r => r.status === 'completed').length
|
||||
const failed = waveResults.filter(r => r.status === 'failed').length
|
||||
// Output: "Wave {wave}: {completed} completed, {failed} failed"
|
||||
}
|
||||
```
|
||||
|
||||
**Instruction Template** (embedded — see instructions/agent-instruction.md for standalone):
|
||||
|
||||
```javascript
|
||||
function buildInstructionTemplate(sessionFolder, wave) {
|
||||
const phaseNames = {
|
||||
1: 'Global Survey', 2: 'Theoretical Foundations', 3: 'Algorithm Design',
|
||||
4: 'Module Implementation', 5: 'Local Function-Level', 6: 'Integration & QA'
|
||||
}
|
||||
return `## TASK ASSIGNMENT — ${phaseNames[wave]}
|
||||
|
||||
### MANDATORY FIRST STEPS
|
||||
1. Read shared discoveries: ${sessionFolder}/discoveries.ndjson (if exists, skip if not)
|
||||
2. Read project context: .workflow/project-tech.json (if exists)
|
||||
|
||||
---
|
||||
|
||||
## Your Task
|
||||
|
||||
**Task ID**: {id}
|
||||
**Title**: {title}
|
||||
**Role**: {track_role}
|
||||
**Analysis Dimension**: {analysis_dimension}
|
||||
**Description**: {description}
|
||||
**Formula References**: {formula_refs}
|
||||
**Precision Requirement**: {precision_req}
|
||||
**Scope**: {scope}
|
||||
|
||||
### Previous Tasks' Findings (Context)
|
||||
{prev_context}
|
||||
|
||||
---
|
||||
|
||||
## Execution Protocol
|
||||
|
||||
1. **Read discoveries**: Load ${sessionFolder}/discoveries.ndjson for shared exploration findings
|
||||
2. **Use context**: Apply previous tasks' findings from prev_context above
|
||||
3. **Execute analysis**:
|
||||
- Read target files within scope: {scope}
|
||||
- Apply analysis criteria for dimension: {analysis_dimension}
|
||||
- Document mathematical formulas in LaTeX notation ($$...$$)
|
||||
- Classify findings by severity (Critical/High/Medium/Low)
|
||||
- Include file:line references for code-related findings
|
||||
4. **Generate document**: Write analysis report to ${sessionFolder}/docs/ following the standard template:
|
||||
- Metadata (Phase, Track, Date)
|
||||
- Executive Summary
|
||||
- Analysis Scope
|
||||
- Findings with severity, evidence, LaTeX formulas, impact, recommendations
|
||||
- Cross-References to other phases
|
||||
- Perspective Package (structured summary for context propagation)
|
||||
5. **Share discoveries**: Append exploration findings to shared board:
|
||||
\`\`\`bash
|
||||
echo '{"ts":"<ISO8601>","worker":"{id}","type":"<type>","data":{...}}' >> ${sessionFolder}/discoveries.ndjson
|
||||
\`\`\`
|
||||
6. **Report result**: Return JSON via report_agent_job_result
|
||||
|
||||
### Discovery Types to Share
|
||||
- \`governing_equation\`: {eq_name, latex, domain, boundary_conditions} — Governing equations found
|
||||
- \`numerical_method\`: {method_name, type, order, stability_class} — Numerical methods identified
|
||||
- \`stability_issue\`: {location, condition_number, severity, description} — Stability concerns
|
||||
- \`convergence_property\`: {method, rate, order, conditions} — Convergence properties
|
||||
- \`precision_risk\`: {location, operation, risk_type, recommendation} — Floating-point precision risks
|
||||
- \`performance_bottleneck\`: {location, operation_count, memory_pattern, suggestion} — Performance issues
|
||||
- \`architecture_pattern\`: {pattern_name, files, description} — Architecture patterns found
|
||||
- \`test_gap\`: {component, missing_coverage, priority} — Missing test coverage
|
||||
|
||||
---
|
||||
|
||||
## Output (report_agent_job_result)
|
||||
|
||||
Return JSON:
|
||||
{
|
||||
"id": "{id}",
|
||||
"status": "completed" | "failed",
|
||||
"findings": "Key discoveries and conclusions (max 500 chars)",
|
||||
"severity_distribution": "Critical:N High:N Medium:N Low:N",
|
||||
"latex_formulas": "key formulas separated by semicolons",
|
||||
"doc_path": "relative path to generated analysis document",
|
||||
"error": ""
|
||||
}`
|
||||
}
|
||||
```
|
||||
|
||||
**Success Criteria**:
|
||||
- All 6 waves executed in order
|
||||
- Each wave's results merged into master CSV before next wave starts
|
||||
- Dependent tasks skipped when predecessor failed
|
||||
- discoveries.ndjson accumulated across all waves
|
||||
- Analysis documents generated in docs/ directory
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Results Aggregation
|
||||
|
||||
**Objective**: Generate final results and comprehensive human-readable report synthesizing all 6 phases.
|
||||
|
||||
```javascript
|
||||
// 1. Export final results.csv
|
||||
Bash(`cp ${sessionFolder}/tasks.csv ${sessionFolder}/results.csv`)
|
||||
|
||||
// 2. Generate context.md
|
||||
const tasks = parseCsv(Read(`${sessionFolder}/tasks.csv`))
|
||||
const completed = tasks.filter(t => t.status === 'completed').length
|
||||
const failed = tasks.filter(t => t.status === 'failed').length
|
||||
const skipped = tasks.filter(t => t.status === 'skipped').length
|
||||
|
||||
let contextMd = `# Numerical Analysis Report: ${requirement}\n\n`
|
||||
contextMd += `**Session**: ${sessionId}\n`
|
||||
contextMd += `**Date**: ${getUtc8ISOString().substring(0, 10)}\n`
|
||||
contextMd += `**Total Tasks**: ${tasks.length} | Completed: ${completed} | Failed: ${failed} | Skipped: ${skipped}\n\n`
|
||||
|
||||
// Per-wave summary
|
||||
const phaseNames = ['', 'Global Survey', 'Theoretical Foundations', 'Algorithm Design',
|
||||
'Module Implementation', 'Local Function-Level', 'Integration & QA']
|
||||
for (let w = 1; w <= 6; w++) {
|
||||
const waveTasks = tasks.filter(t => t.wave === w)
|
||||
contextMd += `## Wave ${w}: ${phaseNames[w]}\n\n`
|
||||
for (const t of waveTasks) {
|
||||
contextMd += `### ${t.id}: ${t.title} [${t.status}]\n`
|
||||
contextMd += `**Role**: ${t.track_role} | **Dimension**: ${t.analysis_dimension}\n\n`
|
||||
if (t.findings) contextMd += `**Findings**: ${t.findings}\n\n`
|
||||
if (t.latex_formulas) contextMd += `**Key Formulas**:\n$$${t.latex_formulas.split(';').join('$$\n\n$$')}$$\n\n`
|
||||
if (t.severity_distribution) contextMd += `**Issues**: ${t.severity_distribution}\n\n`
|
||||
if (t.doc_path) contextMd += `**Full Report**: [${t.doc_path}](${t.doc_path})\n\n`
|
||||
contextMd += `---\n\n`
|
||||
}
|
||||
}
|
||||
|
||||
// Collected formulas section
|
||||
const allFormulas = tasks.filter(t => t.latex_formulas).flatMap(t =>
|
||||
t.latex_formulas.split(';').map(f => ({ task: t.id, formula: f.trim() }))
|
||||
)
|
||||
if (allFormulas.length > 0) {
|
||||
contextMd += `## Collected Mathematical Formulas\n\n`
|
||||
for (const f of allFormulas) {
|
||||
contextMd += `- **${f.task}**: $$${f.formula}$$\n`
|
||||
}
|
||||
contextMd += `\n`
|
||||
}
|
||||
|
||||
// All discoveries summary
|
||||
contextMd += `## Discovery Board Summary\n\n`
|
||||
contextMd += `See: ${sessionFolder}/discoveries.ndjson\n\n`
|
||||
|
||||
Write(`${sessionFolder}/context.md`, contextMd)
|
||||
|
||||
// 3. Display summary
|
||||
// Output wave-by-wave completion status table
|
||||
```
|
||||
|
||||
**Success Criteria**:
|
||||
- results.csv exported
|
||||
- context.md generated with all findings, formulas, cross-references
|
||||
- Summary displayed to user
|
||||
|
||||
---
|
||||
|
||||
## Shared Discovery Board Protocol
|
||||
|
||||
### Standard Discovery Types
|
||||
|
||||
| Type | Dedup Key | Data Schema | Description |
|
||||
|------|-----------|-------------|-------------|
|
||||
| `governing_equation` | `eq_name` | `{eq_name, latex, domain, boundary_conditions}` | Governing equations found in the project |
|
||||
| `numerical_method` | `method_name` | `{method_name, type, order, stability_class}` | Numerical methods identified |
|
||||
| `stability_issue` | `location` | `{location, condition_number, severity, description}` | Numerical stability concerns |
|
||||
| `convergence_property` | `method` | `{method, rate, order, conditions}` | Convergence properties proven or observed |
|
||||
| `precision_risk` | `location+operation` | `{location, operation, risk_type, recommendation}` | Floating-point precision risks |
|
||||
| `performance_bottleneck` | `location` | `{location, operation_count, memory_pattern, suggestion}` | Performance bottlenecks |
|
||||
| `architecture_pattern` | `pattern_name` | `{pattern_name, files, description}` | Software architecture patterns |
|
||||
| `test_gap` | `component` | `{component, missing_coverage, priority}` | Missing test coverage |
|
||||
|
||||
### Protocol Rules
|
||||
|
||||
1. **Read first**: Always read discoveries.ndjson before starting analysis
|
||||
2. **Write immediately**: Append discoveries as soon as found, don't batch
|
||||
3. **Deduplicate**: Check dedup key before appending (same key = skip)
|
||||
4. **Append-only**: Never clear, modify, or recreate discoveries.ndjson
|
||||
5. **Cross-wave accumulation**: Discoveries persist and accumulate across all 6 waves
|
||||
|
||||
### NDJSON Format
|
||||
|
||||
```jsonl
|
||||
{"ts":"2026-03-04T10:00:00Z","worker":"T1.1","type":"governing_equation","data":{"eq_name":"Navier-Stokes","latex":"\\rho(\\frac{\\partial \\mathbf{v}}{\\partial t} + \\mathbf{v} \\cdot \\nabla \\mathbf{v}) = -\\nabla p + \\mu \\nabla^2 \\mathbf{v}","domain":"fluid_dynamics","boundary_conditions":"no-slip walls, inlet velocity"}}
|
||||
{"ts":"2026-03-04T10:05:00Z","worker":"T2.2","type":"convergence_property","data":{"method":"Galerkin FEM","rate":"optimal","order":"h^{k+1} in L2","conditions":"quasi-uniform mesh, sufficient regularity"}}
|
||||
{"ts":"2026-03-04T10:10:00Z","worker":"T3.2","type":"stability_issue","data":{"location":"src/solver/assembler.rs:142","condition_number":"1e12","severity":"High","description":"Ill-conditioned stiffness matrix for high aspect ratio elements"}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Perspective Reuse Matrix
|
||||
|
||||
Each phase's output serves as context for subsequent phases:
|
||||
|
||||
| Source Phase | P2 Reuse | P3 Reuse | P4 Reuse | P5 Reuse | P6 Reuse |
|
||||
|-------------|---------|---------|---------|---------|---------|
|
||||
| P1 Governing Eqs | Formalize → LaTeX | Constrain method selection | Code-equation mapping | Singularity sources | Correctness baseline |
|
||||
| P1 Architecture | Constrain discretization | Parallel strategy | Module boundaries | Hotspot location | Integration scope |
|
||||
| P1 Validation | - | Benchmark selection | Test criteria | Edge case sources | Final validation |
|
||||
| P2 Formulas | - | Parameter constraints | Loop termination | Precision requirements | Theoretical verification |
|
||||
| P2 Convergence | - | Mesh refinement strategy | Iteration control | Error tolerance | Rate verification |
|
||||
| P2 Complexity | - | Performance baseline | Data structure choice | Optimization targets | Performance comparison |
|
||||
| P3 Pseudocode | - | - | Implementation reference | Line-by-line audit | Regression baseline |
|
||||
| P3 Stability | - | - | Precision selection | Cancellation detection | Numerical verification |
|
||||
| P3 Performance | - | - | Memory layout | Vectorization targets | Benchmark targets |
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Error | Resolution |
|
||||
|-------|------------|
|
||||
| Circular dependency | Detect in wave computation, abort with error message |
|
||||
| Agent timeout | Mark as failed in results, continue with wave |
|
||||
| Agent failed | Mark as failed, skip dependent tasks in later waves |
|
||||
| All agents in wave failed | Log error, offer retry or abort |
|
||||
| CSV parse error | Validate CSV format before execution, show line number |
|
||||
| discoveries.ndjson corrupt | Ignore malformed lines, continue with valid entries |
|
||||
| Continue mode: no session found | List available sessions, prompt user to select |
|
||||
| LaTeX parse error | Store raw formula, flag for manual review |
|
||||
| Scope files not found | Warn and continue with available files |
|
||||
| Precision conflict between tracks | Flag in discoveries, defer to QA_Auditor in Wave 6 |
|
||||
|
||||
---
|
||||
|
||||
## Quality Gates (Per-Wave)
|
||||
|
||||
| Wave | Gate Criteria | Threshold |
|
||||
|------|--------------|-----------|
|
||||
| 1 | Core model identified + architecture mapped + KPI defined | All 3 tracks completed |
|
||||
| 2 | Key formulas in LaTeX + convergence conditions stated + complexity determined | All 3 tracks completed |
|
||||
| 3 | Pseudocode producible + stability assessed + performance predicted | ≥ 2 of 3 tracks completed |
|
||||
| 4 | Code-algorithm mapping complete + data structures reviewed + APIs documented | ≥ 2 of 3 tracks completed |
|
||||
| 5 | Hotspots identified + edge cases cataloged + precision risks flagged | ≥ 2 of 3 tracks completed |
|
||||
| 6 | Test plan complete + benchmarks run + QA report synthesized | All 3 tracks completed |
|
||||
|
||||
---
|
||||
|
||||
## Core Rules
|
||||
|
||||
1. **Start Immediately**: First action is session initialization, then Phase 1
|
||||
2. **Wave Order is Sacred**: Never execute wave N before wave N-1 completes and results are merged
|
||||
3. **CSV is Source of Truth**: Master tasks.csv holds all state
|
||||
4. **Context Propagation**: prev_context built from master CSV findings, not from memory
|
||||
5. **Discovery Board is Append-Only**: Never clear, modify, or recreate discoveries.ndjson
|
||||
6. **Skip on Failure**: If a dependency failed, skip the dependent task
|
||||
7. **Cleanup Temp Files**: Remove wave-{N}.csv after results are merged
|
||||
8. **LaTeX Preservation**: Mathematical formulas must be preserved in LaTeX notation throughout all phases
|
||||
9. **Perspective Compounding**: Each wave MUST receive cumulative context from all preceding waves
|
||||
10. **DO NOT STOP**: Continuous execution until all waves complete or all remaining tasks are skipped
|
||||
@@ -1,179 +0,0 @@
|
||||
# Agent Instruction Template
|
||||
|
||||
Template for generating agent instruction prompts used in `spawn_agents_on_csv`.
|
||||
|
||||
## Key Concept
|
||||
|
||||
The instruction template is a **prompt with column placeholders** (`{column_name}`). When `spawn_agents_on_csv` executes, each agent receives the template with its row's column values substituted.
|
||||
|
||||
**Critical rule**: The instruction template is the ONLY context the agent has. It must be self-contained — the agent cannot access the master CSV or other agents' data.
|
||||
|
||||
---
|
||||
|
||||
## Template
|
||||
|
||||
```markdown
|
||||
## TASK ASSIGNMENT — Numerical Analysis
|
||||
|
||||
### MANDATORY FIRST STEPS
|
||||
1. Read shared discoveries: {session_folder}/discoveries.ndjson (if exists, skip if not)
|
||||
2. Read project context: .workflow/project-tech.json (if exists)
|
||||
|
||||
---
|
||||
|
||||
## Your Task
|
||||
|
||||
**Task ID**: {id}
|
||||
**Title**: {title}
|
||||
**Role**: {track_role}
|
||||
**Analysis Dimension**: {analysis_dimension}
|
||||
**Description**: {description}
|
||||
**Formula References**: {formula_refs}
|
||||
**Precision Requirement**: {precision_req}
|
||||
**Scope**: {scope}
|
||||
|
||||
### Previous Tasks' Findings (Context)
|
||||
{prev_context}
|
||||
|
||||
---
|
||||
|
||||
## Execution Protocol
|
||||
|
||||
1. **Read discoveries**: Load {session_folder}/discoveries.ndjson for shared exploration findings from other tracks
|
||||
2. **Use context**: Apply previous tasks' findings from prev_context above — this contains cumulative analysis from all preceding phases
|
||||
3. **Execute analysis based on your role**:
|
||||
|
||||
#### For Domain Analysis Roles (Wave 1: Problem_Domain_Analyst, Software_Architect, Validation_Strategist)
|
||||
- Survey the project codebase within scope: {scope}
|
||||
- Identify mathematical models, governing equations, boundary conditions
|
||||
- Map software architecture: modules, data flow, dependencies
|
||||
- Define validation strategy: benchmarks, KPIs, acceptance criteria
|
||||
|
||||
#### For Theory Roles (Wave 2: Mathematician, Convergence_Analyst, Complexity_Analyst)
|
||||
- Build on governing equations from Wave 1 context
|
||||
- Derive precise mathematical formulations using LaTeX notation
|
||||
- Prove or analyze convergence properties with error bounds
|
||||
- Determine computational complexity (time and space)
|
||||
- All formulas MUST use LaTeX: `$$formula$$`
|
||||
|
||||
#### For Algorithm Roles (Wave 3: Algorithm_Designer, Stability_Analyst, Performance_Modeler)
|
||||
- Select numerical methods based on theoretical analysis from Wave 2
|
||||
- Write algorithm pseudocode for core computational kernels
|
||||
- Analyze condition numbers and error propagation
|
||||
- Build performance model: FLOPS count, memory bandwidth, parallel efficiency
|
||||
|
||||
#### For Module Roles (Wave 4: Module_Implementer, Data_Structure_Designer, Interface_Analyst)
|
||||
- Map algorithms from Wave 3 to actual code modules
|
||||
- Review data structures: sparse matrix formats, mesh data, memory layout
|
||||
- Document module interfaces, data contracts, error handling patterns
|
||||
|
||||
#### For Local Analysis Roles (Wave 5: Code_Optimizer, Edge_Case_Analyst, Precision_Auditor)
|
||||
- Identify performance hotspots with file:line references
|
||||
- Catalog edge cases: singularities, division by zero, overflow/underflow
|
||||
- Audit floating-point operations for catastrophic cancellation, accumulation errors
|
||||
- Provide specific optimization recommendations (vectorization, cache, parallelism)
|
||||
|
||||
#### For Integration Roles (Wave 6: Integration_Tester, Benchmark_Engineer, QA_Auditor)
|
||||
- Design end-to-end test plans using benchmarks from Wave 1
|
||||
- Run or plan performance benchmarks comparing actual vs theoretical (Wave 3)
|
||||
- Synthesize ALL findings from Waves 1-5 into final quality report
|
||||
- Produce risk matrix and improvement roadmap
|
||||
|
||||
4. **Generate analysis document**: Write to {session_folder}/docs/ using this template:
|
||||
|
||||
```markdown
|
||||
# [Phase {wave}] {title}
|
||||
|
||||
## Metadata
|
||||
- **Phase**: {wave} | **Track**: {id} | **Role**: {track_role}
|
||||
- **Dimension**: {analysis_dimension}
|
||||
- **Date**: [ISO8601]
|
||||
- **Input Context**: Context from tasks {context_from}
|
||||
|
||||
## Executive Summary
|
||||
[2-3 sentences: core conclusions]
|
||||
|
||||
## Analysis Scope
|
||||
[Boundaries, assumptions, files analyzed within {scope}]
|
||||
|
||||
## Findings
|
||||
|
||||
### Finding 1: [Title]
|
||||
**Severity**: Critical / High / Medium / Low
|
||||
**Evidence**: [Code reference file:line or formula derivation]
|
||||
$$\text{LaTeX formula if applicable}$$
|
||||
**Impact**: [Effect on project correctness, performance, or stability]
|
||||
**Recommendation**: [Specific actionable suggestion]
|
||||
|
||||
### Finding N: ...
|
||||
|
||||
## Mathematical Formulas
|
||||
[All key formulas derived or referenced in this analysis]
|
||||
|
||||
## Cross-References
|
||||
[References to findings from other phases/tracks]
|
||||
|
||||
## Perspective Package
|
||||
[Structured summary for context propagation to later phases]
|
||||
- Key conclusions: ...
|
||||
- Formulas for reuse: ...
|
||||
- Open questions: ...
|
||||
- Risks identified: ...
|
||||
```
|
||||
|
||||
5. **Share discoveries**: Append findings to shared board:
|
||||
```bash
|
||||
echo '{"ts":"<ISO8601>","worker":"{id}","type":"<type>","data":{...}}' >> {session_folder}/discoveries.ndjson
|
||||
```
|
||||
|
||||
6. **Report result**: Return JSON via report_agent_job_result
|
||||
|
||||
### Discovery Types to Share
|
||||
- `governing_equation`: {eq_name, latex, domain, boundary_conditions} — Governing equations found
|
||||
- `numerical_method`: {method_name, type, order, stability_class} — Numerical methods identified
|
||||
- `stability_issue`: {location, condition_number, severity, description} — Stability concerns
|
||||
- `convergence_property`: {method, rate, order, conditions} — Convergence properties
|
||||
- `precision_risk`: {location, operation, risk_type, recommendation} — Float precision risks
|
||||
- `performance_bottleneck`: {location, operation_count, memory_pattern, suggestion} — Performance issues
|
||||
- `architecture_pattern`: {pattern_name, files, description} — Architecture patterns found
|
||||
- `test_gap`: {component, missing_coverage, priority} — Missing test coverage
|
||||
|
||||
---
|
||||
|
||||
## Output (report_agent_job_result)
|
||||
|
||||
Return JSON:
|
||||
{
|
||||
"id": "{id}",
|
||||
"status": "completed" | "failed",
|
||||
"findings": "Key discoveries and conclusions (max 500 chars)",
|
||||
"severity_distribution": "Critical:N High:N Medium:N Low:N",
|
||||
"latex_formulas": "key formulas in LaTeX separated by semicolons",
|
||||
"doc_path": "relative path to generated analysis document (e.g., docs/P2_Mathematical_Formulation.md)",
|
||||
"error": ""
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Placeholder Distinction
|
||||
|
||||
| Syntax | Resolved By | When |
|
||||
|--------|-----------|------|
|
||||
| `{column_name}` | spawn_agents_on_csv | During agent execution (runtime) |
|
||||
| `{session_folder}` | Wave engine | Before spawning (set in instruction string) |
|
||||
|
||||
The SKILL.md embeds this template with `{session_folder}` replaced by the actual session path. Column placeholders `{column_name}` remain for runtime substitution.
|
||||
|
||||
---
|
||||
|
||||
## Instruction Size Guidelines
|
||||
|
||||
| Track Type | Target Length | Notes |
|
||||
|-----------|-------------|-------|
|
||||
| Wave 1 (Global) | 500-1000 chars | Broad survey, needs exploration guidance |
|
||||
| Wave 2 (Theory) | 1000-2000 chars | Requires mathematical rigor instructions |
|
||||
| Wave 3 (Algorithm) | 1000-1500 chars | Needs pseudocode format guidance |
|
||||
| Wave 4 (Module) | 800-1200 chars | Focused on code-algorithm mapping |
|
||||
| Wave 5 (Local) | 800-1500 chars | Detailed precision/optimization criteria |
|
||||
| Wave 6 (Integration) | 1500-2500 chars | Must synthesize all prior phases |
|
||||
@@ -1,162 +0,0 @@
|
||||
# Numerical Analysis Workflow — CSV Schema
|
||||
|
||||
## Master CSV: tasks.csv
|
||||
|
||||
### Column Definitions
|
||||
|
||||
#### Input Columns (Set by Decomposer)
|
||||
|
||||
| Column | Type | Required | Description | Example |
|
||||
|--------|------|----------|-------------|---------|
|
||||
| `id` | string | Yes | Unique task identifier (T{wave}.{track}) | `"T2.1"` |
|
||||
| `title` | string | Yes | Short task title | `"Mathematical Formulation"` |
|
||||
| `description` | string | Yes | Detailed task description (self-contained) | `"Derive precise mathematical formulations..."` |
|
||||
| `track_role` | string | Yes | Analysis role name | `"Mathematician"` |
|
||||
| `analysis_dimension` | string | Yes | Analysis focus area | `"formula_derivation"` |
|
||||
| `formula_refs` | string | No | References to formulas from earlier tasks (TaskID:formula_name;...) | `"T1.1:governing_eqs;T2.2:convergence_conds"` |
|
||||
| `precision_req` | string | No | Required floating-point precision | `"double"` |
|
||||
| `scope` | string | No | File/directory scope for analysis (glob) | `"src/solver/**"` |
|
||||
| `deps` | string | No | Semicolon-separated dependency task IDs | `"T2.1;T2.2"` |
|
||||
| `context_from` | string | No | Semicolon-separated task IDs for context | `"T1.1;T2.1"` |
|
||||
|
||||
#### Computed Columns (Set by Wave Engine)
|
||||
|
||||
| Column | Type | Description | Example |
|
||||
|--------|------|-------------|---------|
|
||||
| `wave` | integer | Wave number (1-6, fixed per diamond topology) | `3` |
|
||||
| `prev_context` | string | Aggregated findings + formulas from context_from tasks (per-wave CSV only) | `"[T2.1] Weak form derived..."` |
|
||||
|
||||
#### Output Columns (Set by Agent)
|
||||
|
||||
| Column | Type | Description | Example |
|
||||
|--------|------|-------------|---------|
|
||||
| `status` | enum | `pending` → `completed` / `failed` / `skipped` | `"completed"` |
|
||||
| `findings` | string | Key discoveries (max 500 chars) | `"Identified CFL condition..."` |
|
||||
| `severity_distribution` | string | Issue counts by severity | `"Critical:0 High:2 Medium:3 Low:1"` |
|
||||
| `latex_formulas` | string | Key LaTeX formulas (semicolon-separated) | `"\\Delta t \\leq \\frac{h}{c};\\kappa(A) = \\|A\\|\\|A^{-1}\\|"` |
|
||||
| `doc_path` | string | Path to generated analysis document | `"docs/P3_Numerical_Stability_Report.md"` |
|
||||
| `error` | string | Error message if failed | `""` |
|
||||
|
||||
---
|
||||
|
||||
### Example Data
|
||||
|
||||
```csv
|
||||
id,title,description,track_role,analysis_dimension,formula_refs,precision_req,scope,deps,context_from,wave,status,findings,severity_distribution,latex_formulas,doc_path,error
|
||||
"T1.1","Problem Domain Survey","Survey governing equations and mathematical models. Identify PDE types, boundary conditions, conservation laws, and physical domain.","Problem_Domain_Analyst","domain_modeling","","","src/**","","","1","completed","Identified Navier-Stokes equations with k-epsilon turbulence model. Incompressible flow assumption. No-slip boundary conditions.","Critical:0 High:0 Medium:1 Low:2","\\rho(\\frac{\\partial v}{\\partial t} + v \\cdot \\nabla v) = -\\nabla p + \\mu \\nabla^2 v","docs/P1_Domain_Survey.md",""
|
||||
"T2.1","Mathematical Formulation","Derive precise mathematical formulations using LaTeX. Transform governing equations into weak forms suitable for FEM discretization.","Mathematician","formula_derivation","T1.1:governing_eqs","","src/**","T1.1","T1.1","2","completed","Weak form derived for NS equations. Galerkin formulation with inf-sup stable elements (Taylor-Hood P2/P1).","Critical:0 High:0 Medium:0 Low:1","\\int_\\Omega \\mu \\nabla u : \\nabla v \\, d\\Omega - \\int_\\Omega p \\nabla \\cdot v \\, d\\Omega = \\int_\\Omega f \\cdot v \\, d\\Omega","docs/P2_Mathematical_Formulation.md",""
|
||||
"T3.2","Numerical Stability Report","Analyze numerical stability of selected algorithms. Evaluate condition numbers, error propagation characteristics, and precision requirements.","Stability_Analyst","stability_analysis","T2.1:weak_forms;T2.2:convergence_conds","double","src/solver/**","T2.1;T2.2","T2.1;T2.2","3","pending","","","","",""
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Column Lifecycle
|
||||
|
||||
```
|
||||
Decomposer (Phase 1) Wave Engine (Phase 2) Agent (Execution)
|
||||
───────────────────── ──────────────────── ─────────────────
|
||||
id ───────────► id ──────────► id
|
||||
title ───────────► title ──────────► (reads)
|
||||
description ───────────► description ──────────► (reads)
|
||||
track_role ───────────► track_role ──────────► (reads)
|
||||
analysis_dimension ─────► analysis_dimension ────► (reads)
|
||||
formula_refs ──────────► formula_refs ─────────► (reads)
|
||||
precision_req ─────────► precision_req ─────────► (reads)
|
||||
scope ───────────► scope ──────────► (reads)
|
||||
deps ───────────► deps ──────────► (reads)
|
||||
context_from───────────► context_from──────────► (reads)
|
||||
wave ──────────► (reads)
|
||||
prev_context ──────────► (reads)
|
||||
status
|
||||
findings
|
||||
severity_distribution
|
||||
latex_formulas
|
||||
doc_path
|
||||
error
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output Schema (JSON)
|
||||
|
||||
Agent output via `report_agent_job_result`:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"id": { "type": "string", "description": "Task ID (T{wave}.{track})" },
|
||||
"status": { "type": "string", "enum": ["completed", "failed"] },
|
||||
"findings": { "type": "string", "description": "Key discoveries, max 500 chars" },
|
||||
"severity_distribution": { "type": "string", "description": "Critical:N High:N Medium:N Low:N" },
|
||||
"latex_formulas": { "type": "string", "description": "Key formulas in LaTeX, semicolon-separated" },
|
||||
"doc_path": { "type": "string", "description": "Path to generated analysis document" },
|
||||
"error": { "type": "string", "description": "Error message if failed" }
|
||||
},
|
||||
"required": ["id", "status", "findings"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Discovery Types
|
||||
|
||||
| Type | Dedup Key | Data Schema | Description |
|
||||
|------|-----------|-------------|-------------|
|
||||
| `governing_equation` | `eq_name` | `{eq_name, latex, domain, boundary_conditions}` | Governing equations found |
|
||||
| `numerical_method` | `method_name` | `{method_name, type, order, stability_class}` | Numerical methods identified |
|
||||
| `stability_issue` | `location` | `{location, condition_number, severity, description}` | Stability concerns |
|
||||
| `convergence_property` | `method` | `{method, rate, order, conditions}` | Convergence properties |
|
||||
| `precision_risk` | `location+operation` | `{location, operation, risk_type, recommendation}` | Float precision risks |
|
||||
| `performance_bottleneck` | `location` | `{location, operation_count, memory_pattern, suggestion}` | Performance bottlenecks |
|
||||
| `architecture_pattern` | `pattern_name` | `{pattern_name, files, description}` | Architecture patterns |
|
||||
| `test_gap` | `component` | `{component, missing_coverage, priority}` | Missing test coverage |
|
||||
|
||||
### Discovery NDJSON Format
|
||||
|
||||
```jsonl
|
||||
{"ts":"2026-03-04T10:00:00Z","worker":"T1.1","type":"governing_equation","data":{"eq_name":"Navier-Stokes","latex":"\\rho(\\frac{\\partial v}{\\partial t} + v \\cdot \\nabla v) = -\\nabla p + \\mu \\nabla^2 v","domain":"fluid_dynamics","boundary_conditions":"no-slip walls"}}
|
||||
{"ts":"2026-03-04T10:05:00Z","worker":"T2.2","type":"convergence_property","data":{"method":"Galerkin FEM","rate":"optimal","order":"h^{k+1}","conditions":"quasi-uniform mesh"}}
|
||||
{"ts":"2026-03-04T10:10:00Z","worker":"T3.2","type":"stability_issue","data":{"location":"src/solver/assembler.rs:142","condition_number":"1e12","severity":"High","description":"Ill-conditioned stiffness matrix"}}
|
||||
{"ts":"2026-03-04T10:15:00Z","worker":"T5.3","type":"precision_risk","data":{"location":"src/solver/residual.rs:87","operation":"subtraction of nearly equal values","risk_type":"catastrophic_cancellation","recommendation":"Use compensated summation or reformulate"}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Rules
|
||||
|
||||
| Rule | Check | Error |
|
||||
|------|-------|-------|
|
||||
| Unique IDs | No duplicate `id` values | "Duplicate task ID: {id}" |
|
||||
| Valid deps | All dep IDs exist in tasks | "Unknown dependency: {dep_id}" |
|
||||
| No self-deps | Task cannot depend on itself | "Self-dependency: {id}" |
|
||||
| No circular deps | Topological sort completes | "Circular dependency detected involving: {ids}" |
|
||||
| context_from valid | All context IDs exist and in earlier waves | "Invalid context_from: {id}" |
|
||||
| Description non-empty | Every task has description | "Empty description for task: {id}" |
|
||||
| Status enum | status in {pending, completed, failed, skipped} | "Invalid status: {status}" |
|
||||
| Wave range | wave in {1..6} | "Invalid wave number: {wave}" |
|
||||
| Track role valid | track_role matches known roles | "Unknown track_role: {role}" |
|
||||
| Formula refs format | TaskID:formula_name pattern | "Malformed formula_refs: {value}" |
|
||||
|
||||
### Analysis Dimension Values
|
||||
|
||||
| Dimension | Used In Wave | Description |
|
||||
|-----------|-------------|-------------|
|
||||
| `domain_modeling` | 1 | Physical/mathematical domain survey |
|
||||
| `architecture_analysis` | 1 | Software architecture analysis |
|
||||
| `validation_design` | 1 | Validation and benchmark strategy |
|
||||
| `formula_derivation` | 2 | Mathematical formulation and derivation |
|
||||
| `convergence_analysis` | 2 | Convergence theory and error bounds |
|
||||
| `complexity_analysis` | 2 | Computational complexity analysis |
|
||||
| `method_selection` | 3 | Numerical method selection and design |
|
||||
| `stability_analysis` | 3 | Numerical stability assessment |
|
||||
| `performance_modeling` | 3 | Performance prediction and modeling |
|
||||
| `implementation_analysis` | 4 | Module-level code analysis |
|
||||
| `data_structure_review` | 4 | Data structure and memory layout review |
|
||||
| `interface_analysis` | 4 | API contract and interface analysis |
|
||||
| `optimization` | 5 | Function-level performance optimization |
|
||||
| `edge_case_analysis` | 5 | Boundary and singularity handling |
|
||||
| `precision_audit` | 5 | Floating-point precision audit |
|
||||
| `integration_testing` | 6 | System integration testing |
|
||||
| `benchmarking` | 6 | Performance benchmarking |
|
||||
| `quality_assurance` | 6 | Final quality audit and synthesis |
|
||||
@@ -1,237 +0,0 @@
|
||||
# Analysis Dimensions for Numerical Computation
|
||||
|
||||
Defines the 18 analysis dimensions across 6 phases of the NADW workflow.
|
||||
|
||||
## Purpose
|
||||
|
||||
| Phase | Usage |
|
||||
|-------|-------|
|
||||
| Phase 1 (Decomposition) | Reference when assigning analysis_dimension to tasks |
|
||||
| Phase 2 (Execution) | Agents use to understand their analysis focus |
|
||||
| Phase 3 (Aggregation) | Organize findings by dimension |
|
||||
|
||||
---
|
||||
|
||||
## 1. Wave 1: Global Survey Dimensions
|
||||
|
||||
### 1.1 Domain Modeling (`domain_modeling`)
|
||||
|
||||
**Analyst Role**: Problem_Domain_Analyst
|
||||
|
||||
**Focus Areas**:
|
||||
- Governing equations (PDEs, ODEs, integral equations)
|
||||
- Physical domain and boundary conditions
|
||||
- Conservation laws and constitutive relations
|
||||
- Problem classification (elliptic, parabolic, hyperbolic)
|
||||
- Dimensional analysis and non-dimensionalization
|
||||
|
||||
**Key Outputs**:
|
||||
- Equation inventory with LaTeX notation
|
||||
- Boundary condition catalog
|
||||
- Problem classification matrix
|
||||
- Physical parameter ranges
|
||||
|
||||
**Formula Types to Identify**:
|
||||
$$\frac{\partial u}{\partial t} + \mathcal{L}u = f \quad \text{(general PDE form)}$$
|
||||
$$u|_{\partial\Omega} = g \quad \text{(Dirichlet BC)}$$
|
||||
$$\frac{\partial u}{\partial n}|_{\partial\Omega} = h \quad \text{(Neumann BC)}$$
|
||||
|
||||
### 1.2 Architecture Analysis (`architecture_analysis`)
|
||||
|
||||
**Analyst Role**: Software_Architect
|
||||
|
||||
**Focus Areas**:
|
||||
- Module decomposition and dependency graph
|
||||
- Data flow between computational stages
|
||||
- I/O patterns (mesh input, solution output, checkpointing)
|
||||
- Parallelism strategy (MPI, OpenMP, GPU)
|
||||
- Build system and dependency management
|
||||
|
||||
**Key Outputs**:
|
||||
- High-level component diagram
|
||||
- Data flow diagram
|
||||
- Technology stack inventory
|
||||
- Parallelism strategy assessment
|
||||
|
||||
### 1.3 Validation Design (`validation_design`)
|
||||
|
||||
**Analyst Role**: Validation_Strategist
|
||||
|
||||
**Focus Areas**:
|
||||
- Benchmark cases with known analytical solutions
|
||||
- Manufactured solution methodology
|
||||
- Grid convergence study design
|
||||
- Key Performance Indicators (KPIs)
|
||||
- Acceptance criteria definition
|
||||
|
||||
**Key Outputs**:
|
||||
- Benchmark case catalog
|
||||
- Validation methodology matrix
|
||||
- KPI definitions with targets
|
||||
- Acceptance test specifications
|
||||
|
||||
---
|
||||
|
||||
## 2. Wave 2: Theoretical Foundation Dimensions
|
||||
|
||||
### 2.1 Formula Derivation (`formula_derivation`)
|
||||
|
||||
**Analyst Role**: Mathematician
|
||||
|
||||
**Focus Areas**:
|
||||
- Strong-to-weak form transformation
|
||||
- Discretization schemes (FEM, FDM, FVM, spectral)
|
||||
- Variational formulations
|
||||
- Linearization techniques (Newton, Picard)
|
||||
- Stabilization methods (SUPG, GLS, VMS)
|
||||
|
||||
**Key Formula Templates**:
|
||||
$$\text{Weak form: } a(u,v) = l(v) \quad \forall v \in V_h$$
|
||||
$$a(u,v) = \int_\Omega \nabla u \cdot \nabla v \, d\Omega$$
|
||||
$$l(v) = \int_\Omega f v \, d\Omega + \int_{\Gamma_N} g v \, dS$$
|
||||
|
||||
### 2.2 Convergence Analysis (`convergence_analysis`)
|
||||
|
||||
**Analyst Role**: Convergence_Analyst
|
||||
|
||||
**Focus Areas**:
|
||||
- A priori error estimates
|
||||
- A posteriori error estimators
|
||||
- Convergence order verification
|
||||
- Lax equivalence theorem applicability
|
||||
- CFL conditions for time-dependent problems
|
||||
|
||||
**Key Formula Templates**:
|
||||
$$\|u - u_h\|_{L^2} \leq C h^{k+1} |u|_{H^{k+1}} \quad \text{(optimal L2 rate)}$$
|
||||
$$\|u - u_h\|_{H^1} \leq C h^k |u|_{H^{k+1}} \quad \text{(optimal H1 rate)}$$
|
||||
$$\Delta t \leq \frac{C h}{\|v\|_\infty} \quad \text{(CFL condition)}$$
|
||||
|
||||
### 2.3 Complexity Analysis (`complexity_analysis`)
|
||||
|
||||
**Analyst Role**: Complexity_Analyst
|
||||
|
||||
**Focus Areas**:
|
||||
- Assembly operation counts
|
||||
- Solver complexity (direct vs iterative)
|
||||
- Preconditioner cost analysis
|
||||
- Memory scaling with problem size
|
||||
- Communication overhead in parallel settings
|
||||
|
||||
**Key Formula Templates**:
|
||||
$$T_{assembly} = O(N_{elem} \cdot p^{2d}) \quad \text{(FEM assembly)}$$
|
||||
$$T_{solve} = O(N^{3/2}) \quad \text{(2D direct)}, \quad O(N \log N) \quad \text{(multigrid)}$$
|
||||
$$M_{storage} = O(nnz) \quad \text{(sparse storage)}$$
|
||||
|
||||
---
|
||||
|
||||
## 3. Wave 3: Algorithm Design Dimensions
|
||||
|
||||
### 3.1 Method Selection (`method_selection`)
|
||||
|
||||
**Analyst Role**: Algorithm_Designer
|
||||
|
||||
**Focus Areas**:
|
||||
- Spatial discretization method selection
|
||||
- Time integration scheme selection
|
||||
- Linear/nonlinear solver selection
|
||||
- Preconditioner selection
|
||||
- Mesh generation strategy
|
||||
|
||||
**Decision Criteria**:
|
||||
|
||||
| Criterion | Weight | Metrics |
|
||||
|-----------|--------|---------|
|
||||
| Accuracy order | High | Convergence rate, error bounds |
|
||||
| Stability | High | Unconditional vs conditional, CFL |
|
||||
| Efficiency | Medium | FLOPS per DOF, memory per DOF |
|
||||
| Parallelizability | Medium | Communication-to-computation ratio |
|
||||
| Implementation complexity | Low | Lines of code, library availability |
|
||||
|
||||
### 3.2 Stability Analysis (`stability_analysis`)
|
||||
|
||||
**Analyst Role**: Stability_Analyst
|
||||
|
||||
**Focus Areas**:
|
||||
- Von Neumann stability analysis
|
||||
- Matrix condition numbers
|
||||
- Amplification factors
|
||||
- Inf-sup (LBB) stability for mixed methods
|
||||
- Mesh-dependent stability bounds
|
||||
|
||||
**Key Formula Templates**:
|
||||
$$\kappa(A) = \|A\| \cdot \|A^{-1}\| \quad \text{(condition number)}$$
|
||||
$$|g(\xi)| \leq 1 \quad \forall \xi \quad \text{(von Neumann stability)}$$
|
||||
$$\inf_{q_h \in Q_h} \sup_{v_h \in V_h} \frac{b(v_h, q_h)}{\|v_h\| \|q_h\|} \geq \beta > 0 \quad \text{(inf-sup)}$$
|
||||
|
||||
### 3.3 Performance Modeling (`performance_modeling`)
|
||||
|
||||
**Analyst Role**: Performance_Modeler
|
||||
|
||||
**Focus Areas**:
|
||||
- Arithmetic intensity (FLOPS/byte)
|
||||
- Roofline model analysis
|
||||
- Strong/weak scaling prediction
|
||||
- Memory bandwidth bottleneck identification
|
||||
- Cache utilization estimates
|
||||
|
||||
**Key Formula Templates**:
|
||||
$$AI = \frac{\text{FLOPS}}{\text{Bytes transferred}} \quad \text{(arithmetic intensity)}$$
|
||||
$$P_{max} = \min(P_{peak}, AI \times BW_{mem}) \quad \text{(roofline bound)}$$
|
||||
$$E_{parallel}(p) = \frac{T_1}{p \cdot T_p} \quad \text{(parallel efficiency)}$$
|
||||
|
||||
---
|
||||
|
||||
## 4. Wave 4: Module Implementation Dimensions
|
||||
|
||||
### 4.1 Implementation Analysis (`implementation_analysis`)
|
||||
|
||||
**Focus**: Algorithm-to-code mapping, implementation correctness, coding patterns
|
||||
|
||||
### 4.2 Data Structure Review (`data_structure_review`)
|
||||
|
||||
**Focus**: Sparse matrix formats (CSR/CSC/COO), mesh data structures, memory layout optimization
|
||||
|
||||
### 4.3 Interface Analysis (`interface_analysis`)
|
||||
|
||||
**Focus**: Module APIs, data contracts between components, error handling patterns
|
||||
|
||||
---
|
||||
|
||||
## 5. Wave 5: Local Function-Level Dimensions
|
||||
|
||||
### 5.1 Optimization (`optimization`)
|
||||
|
||||
**Focus**: Hotspot identification, vectorization opportunities, cache optimization, loop restructuring
|
||||
|
||||
### 5.2 Edge Case Analysis (`edge_case_analysis`)
|
||||
|
||||
**Focus**: Division by zero, matrix singularity, degenerate mesh elements, boundary layer singularities
|
||||
|
||||
### 5.3 Precision Audit (`precision_audit`)
|
||||
|
||||
**Focus**: Catastrophic cancellation, accumulation errors, mixed-precision opportunities, compensated algorithms
|
||||
|
||||
**Critical Patterns to Detect**:
|
||||
|
||||
| Pattern | Risk | Mitigation |
|
||||
|---------|------|-----------|
|
||||
| `a - b` where `a ≈ b` | Catastrophic cancellation | Reformulate or use higher precision |
|
||||
| `sum += small_value` in loop | Accumulation error | Kahan summation |
|
||||
| `1.0/x` where `x → 0` | Overflow/loss of significance | Guard with threshold |
|
||||
| Mixed float32/float64 | Silent precision loss | Explicit type annotations |
|
||||
|
||||
---
|
||||
|
||||
## 6. Wave 6: Integration & QA Dimensions
|
||||
|
||||
### 6.1 Integration Testing (`integration_testing`)
|
||||
|
||||
**Focus**: End-to-end test design, regression suite, manufactured solutions verification
|
||||
|
||||
### 6.2 Benchmarking (`benchmarking`)
|
||||
|
||||
**Focus**: Actual vs predicted performance, scalability tests, profiling results
|
||||
|
||||
### 6.3 Quality Assurance (`quality_assurance`)
|
||||
|
||||
**Focus**: All-phase synthesis, risk matrix, improvement roadmap, final recommendations
|
||||
@@ -1,214 +0,0 @@
|
||||
# Phase Topology — Diamond Deep Tree
|
||||
|
||||
Wave coordination patterns for the Numerical Analysis Diamond Workflow (NADW).
|
||||
|
||||
## Purpose
|
||||
|
||||
| Phase | Usage |
|
||||
|-------|-------|
|
||||
| Phase 1 (Decomposition) | Reference when assigning waves and dependencies |
|
||||
| Phase 2 (Execution) | Context flow between waves |
|
||||
| Phase 3 (Aggregation) | Structure the final report by topology |
|
||||
|
||||
---
|
||||
|
||||
## 1. Topology Overview
|
||||
|
||||
The NADW uses a **Staged Diamond** topology — six sequential waves, each with 3 parallel tracks. Context flows cumulatively from earlier waves to later ones.
|
||||
|
||||
```
|
||||
Wave 1: [T1.1] [T1.2] [T1.3] Global Survey (3 parallel)
|
||||
↓ Context P1
|
||||
Wave 2: [T2.1] [T2.2] [T2.3] Theory (3 parallel)
|
||||
↓ Context P1+P2
|
||||
Wave 3: [T3.1] [T3.2] [T3.3] Algorithm (3 parallel)
|
||||
↓ Context P1+P2+P3
|
||||
Wave 4: [T4.1] [T4.2] [T4.3] Module (3 parallel)
|
||||
↓ Context P1-P4
|
||||
Wave 5: [T5.1] [T5.2] [T5.3] Local (3 parallel)
|
||||
↓ Context P1-P5
|
||||
Wave 6: [T6.1] [T6.2] [T6.3] Integration (3 parallel)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Wave Definitions
|
||||
|
||||
### Wave 1: Global Survey
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Phase Name | Global Survey |
|
||||
| Track Count | 3 |
|
||||
| Dependencies | None (entry wave) |
|
||||
| Context Input | Project codebase only |
|
||||
| Context Output | Governing equations, architecture map, validation KPIs |
|
||||
| Max Parallelism | 3 |
|
||||
|
||||
**Tracks**:
|
||||
| ID | Role | Dimension | Scope |
|
||||
|----|------|-----------|-------|
|
||||
| T1.1 | Problem_Domain_Analyst | domain_modeling | Full project |
|
||||
| T1.2 | Software_Architect | architecture_analysis | Full project |
|
||||
| T1.3 | Validation_Strategist | validation_design | Full project |
|
||||
|
||||
### Wave 2: Theoretical Foundations
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Phase Name | Theoretical Foundations |
|
||||
| Track Count | 3 |
|
||||
| Dependencies | Wave 1 |
|
||||
| Context Input | Context Package P1 |
|
||||
| Context Output | LaTeX formulas, convergence theorems, complexity bounds |
|
||||
| Max Parallelism | 3 |
|
||||
|
||||
**Tracks**:
|
||||
| ID | Role | Dimension | Deps | context_from |
|
||||
|----|------|-----------|------|-------------|
|
||||
| T2.1 | Mathematician | formula_derivation | T1.1 | T1.1 |
|
||||
| T2.2 | Convergence_Analyst | convergence_analysis | T1.1 | T1.1 |
|
||||
| T2.3 | Complexity_Analyst | complexity_analysis | T1.1;T1.2 | T1.1;T1.2 |
|
||||
|
||||
### Wave 3: Algorithm Design & Stability
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Phase Name | Algorithm Design |
|
||||
| Track Count | 3 |
|
||||
| Dependencies | Wave 2 |
|
||||
| Context Input | Context Package P1+P2 |
|
||||
| Context Output | Pseudocode, stability conditions, performance model |
|
||||
| Max Parallelism | 3 |
|
||||
|
||||
**Tracks**:
|
||||
| ID | Role | Dimension | Deps | context_from |
|
||||
|----|------|-----------|------|-------------|
|
||||
| T3.1 | Algorithm_Designer | method_selection | T2.1 | T2.1;T2.2;T2.3 |
|
||||
| T3.2 | Stability_Analyst | stability_analysis | T2.1;T2.2 | T2.1;T2.2 |
|
||||
| T3.3 | Performance_Modeler | performance_modeling | T2.3 | T1.2;T2.3 |
|
||||
|
||||
### Wave 4: Module Implementation
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Phase Name | Module Implementation |
|
||||
| Track Count | 3 |
|
||||
| Dependencies | Wave 3 |
|
||||
| Context Input | Context Package P1-P3 |
|
||||
| Context Output | Code-algorithm mapping, data structure decisions, API contracts |
|
||||
| Max Parallelism | 3 |
|
||||
|
||||
**Tracks**:
|
||||
| ID | Role | Dimension | Deps | context_from |
|
||||
|----|------|-----------|------|-------------|
|
||||
| T4.1 | Module_Implementer | implementation_analysis | T3.1 | T1.2;T3.1 |
|
||||
| T4.2 | Data_Structure_Designer | data_structure_review | T3.1;T3.3 | T2.3;T3.1;T3.3 |
|
||||
| T4.3 | Interface_Analyst | interface_analysis | T3.1 | T1.2;T3.1 |
|
||||
|
||||
### Wave 5: Local Function-Level
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Phase Name | Local Function-Level |
|
||||
| Track Count | 3 |
|
||||
| Dependencies | Wave 4 |
|
||||
| Context Input | Context Package P1-P4 |
|
||||
| Context Output | Optimization recommendations, edge case catalog, precision risk matrix |
|
||||
| Max Parallelism | 3 |
|
||||
|
||||
**Tracks**:
|
||||
| ID | Role | Dimension | Deps | context_from |
|
||||
|----|------|-----------|------|-------------|
|
||||
| T5.1 | Code_Optimizer | optimization | T4.1 | T3.3;T4.1 |
|
||||
| T5.2 | Edge_Case_Analyst | edge_case_analysis | T4.1 | T1.1;T3.2;T4.1 |
|
||||
| T5.3 | Precision_Auditor | precision_audit | T4.1;T4.2 | T3.2;T4.1;T4.2 |
|
||||
|
||||
### Wave 6: Integration & QA
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Phase Name | Integration & QA |
|
||||
| Track Count | 3 |
|
||||
| Dependencies | Wave 5 |
|
||||
| Context Input | Context Package P1-P5 (ALL cumulative) |
|
||||
| Context Output | Final test plan, benchmark report, QA assessment |
|
||||
| Max Parallelism | 3 |
|
||||
|
||||
**Tracks**:
|
||||
| ID | Role | Dimension | Deps | context_from |
|
||||
|----|------|-----------|------|-------------|
|
||||
| T6.1 | Integration_Tester | integration_testing | T5.1;T5.2 | T1.3;T5.1;T5.2 |
|
||||
| T6.2 | Benchmark_Engineer | benchmarking | T5.1 | T1.3;T3.3;T5.1 |
|
||||
| T6.3 | QA_Auditor | quality_assurance | T5.1;T5.2;T5.3 | T1.1;T2.1;T3.1;T4.1;T5.1;T5.2;T5.3 |
|
||||
|
||||
---
|
||||
|
||||
## 3. Context Flow Map
|
||||
|
||||
### Directed Context (prev_context column)
|
||||
|
||||
```
|
||||
T1.1 ──► T2.1, T2.2, T2.3
|
||||
T1.2 ──► T2.3, T3.3, T4.1, T4.3
|
||||
T1.3 ──► T6.1, T6.2
|
||||
T2.1 ──► T3.1, T3.2
|
||||
T2.2 ──► T3.1, T3.2
|
||||
T2.3 ──► T3.1, T3.3, T4.2
|
||||
T3.1 ──► T4.1, T4.2, T4.3
|
||||
T3.2 ──► T5.2, T5.3
|
||||
T3.3 ──► T4.2, T5.1, T6.2
|
||||
T4.1 ──► T5.1, T5.2, T5.3
|
||||
T4.2 ──► T5.3
|
||||
T5.1 ──► T6.1, T6.2
|
||||
T5.2 ──► T6.1
|
||||
T5.3 ──► T6.3
|
||||
```
|
||||
|
||||
### Broadcast Context (discoveries.ndjson)
|
||||
|
||||
All agents read/append to the same discoveries.ndjson. Key discovery types flow across waves:
|
||||
|
||||
```
|
||||
Wave 1: governing_equation, architecture_pattern ──► all subsequent waves
|
||||
Wave 2: convergence_property ──► Wave 3-6
|
||||
Wave 3: stability_issue, numerical_method ──► Wave 4-6
|
||||
Wave 4: (implementation findings) ──► Wave 5-6
|
||||
Wave 5: precision_risk, performance_bottleneck ──► Wave 6
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Perspective Reuse Matrix
|
||||
|
||||
How each wave's output is reused by later waves:
|
||||
|
||||
| Source | P2 Reuse | P3 Reuse | P4 Reuse | P5 Reuse | P6 Reuse |
|
||||
|--------|---------|---------|---------|---------|---------|
|
||||
| **P1 Equations** | Formalize → LaTeX | Constrain methods | Code-eq mapping | Singularity sources | Correctness baseline |
|
||||
| **P1 Architecture** | Constrain discretization | Parallel strategy | Module boundaries | Hotspot location | Integration scope |
|
||||
| **P1 Validation** | - | Benchmark selection | Test criteria | Edge case sources | Final validation |
|
||||
| **P2 Formulas** | - | Parameter constraints | Loop termination | Precision requirements | Theory verification |
|
||||
| **P2 Convergence** | - | Mesh refinement | Iteration control | Error tolerance | Rate verification |
|
||||
| **P2 Complexity** | - | Performance baseline | Data structure choice | Optimization targets | Perf comparison |
|
||||
| **P3 Pseudocode** | - | - | Impl reference | Line-by-line audit | Regression baseline |
|
||||
| **P3 Stability** | - | - | Precision selection | Cancellation detection | Numerical verification |
|
||||
| **P3 Performance** | - | - | Memory layout | Vectorization targets | Benchmark targets |
|
||||
| **P4 Modules** | - | - | - | Function-level focus | Module test plan |
|
||||
| **P5 Optimization** | - | - | - | - | Performance tests |
|
||||
| **P5 Edge Cases** | - | - | - | - | Regression tests |
|
||||
| **P5 Precision** | - | - | - | - | Numerical tests |
|
||||
|
||||
---
|
||||
|
||||
## 5. Diamond Properties
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Total Waves | 6 |
|
||||
| Total Tasks | 18 (3 per wave) |
|
||||
| Max Parallelism per Wave | 3 |
|
||||
| Widest Context Fan-in | T6.3 (receives from 7 tasks) |
|
||||
| Deepest Dependency Chain | T1.1 → T2.1 → T3.1 → T4.1 → T5.1 → T6.1 (depth 6) |
|
||||
| Context Accumulation | Cumulative (each wave adds to previous context) |
|
||||
| Topology Type | Staged Parallel with Diamond convergence at Wave 6 |
|
||||
@@ -1,173 +0,0 @@
|
||||
# Quality Standards for Numerical Analysis Workflow
|
||||
|
||||
Quality assessment criteria for NADW analysis reports.
|
||||
|
||||
## When to Use
|
||||
|
||||
| Phase | Usage | Section |
|
||||
|-------|-------|---------|
|
||||
| Phase 2 (Execution) | Guide agent analysis quality | All dimensions |
|
||||
| Phase 3 (Aggregation) | Score generated reports | Quality Gates |
|
||||
|
||||
---
|
||||
|
||||
## Quality Dimensions
|
||||
|
||||
### 1. Mathematical Rigor (30%)
|
||||
|
||||
| Score | Criteria |
|
||||
|-------|----------|
|
||||
| 100% | All formulas correct, properly derived, LaTeX well-formatted, error bounds proven |
|
||||
| 80% | Formulas correct, some derivation steps skipped, bounds stated without full proof |
|
||||
| 60% | Key formulas present, some notation inconsistencies, bounds estimated |
|
||||
| 40% | Formulas incomplete or contain errors |
|
||||
| 0% | No mathematical content |
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Governing equations identified and written in LaTeX
|
||||
- [ ] Weak forms correctly derived from strong forms
|
||||
- [ ] Convergence order stated with conditions
|
||||
- [ ] Error bounds provided (a priori or a posteriori)
|
||||
- [ ] CFL/stability conditions explicitly stated
|
||||
- [ ] Condition numbers estimated for key matrices
|
||||
- [ ] Complexity bounds (time and space) determined
|
||||
- [ ] LaTeX notation consistent throughout all documents
|
||||
|
||||
### 2. Code-Theory Mapping (25%)
|
||||
|
||||
| Score | Criteria |
|
||||
|-------|----------|
|
||||
| 100% | Every algorithm mapped to code with file:line references, data structures justified |
|
||||
| 80% | Major algorithms mapped, most references accurate |
|
||||
| 60% | Key mappings present, some code references missing |
|
||||
| 40% | Superficial mapping, few code references |
|
||||
| 0% | No code-theory connection |
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Each numerical method traced to implementing function/module
|
||||
- [ ] Data structures justified against algorithm requirements
|
||||
- [ ] Sparse matrix format matched to access patterns
|
||||
- [ ] Time integration scheme identified in code
|
||||
- [ ] Boundary condition implementation verified
|
||||
- [ ] Solver configuration traced to convergence requirements
|
||||
- [ ] Preconditioner choice justified
|
||||
|
||||
### 3. Numerical Quality Assessment (25%)
|
||||
|
||||
| Score | Criteria |
|
||||
|-------|----------|
|
||||
| 100% | Stability fully analyzed, precision risks cataloged, all edge cases covered |
|
||||
| 80% | Stability assessed, major precision risks found, common edge cases covered |
|
||||
| 60% | Basic stability check, some precision risks, incomplete edge cases |
|
||||
| 40% | Superficial stability mention, few precision issues found |
|
||||
| 0% | No numerical quality analysis |
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Condition numbers estimated for key operations
|
||||
- [ ] Catastrophic cancellation risks identified with file:line
|
||||
- [ ] Accumulation error potential assessed
|
||||
- [ ] Float precision choices justified (float32 vs float64)
|
||||
- [ ] Edge cases cataloged (singularities, degenerate inputs)
|
||||
- [ ] Overflow/underflow risks identified
|
||||
- [ ] Mixed-precision operations flagged
|
||||
|
||||
### 4. Cross-Phase Coherence (20%)
|
||||
|
||||
| Score | Criteria |
|
||||
|-------|----------|
|
||||
| 100% | All 6 phases connected, findings build on each other, no contradictions |
|
||||
| 80% | Most phases connected, minor gaps in context propagation |
|
||||
| 60% | Key connections present, some phases isolated |
|
||||
| 40% | Limited cross-referencing between phases |
|
||||
| 0% | Phases completely isolated |
|
||||
|
||||
**Checklist**:
|
||||
- [ ] Wave 2 formulas reference Wave 1 governing equations
|
||||
- [ ] Wave 3 algorithms justified by Wave 2 theory
|
||||
- [ ] Wave 4 implementation verified against Wave 3 pseudocode
|
||||
- [ ] Wave 5 optimization targets from Wave 3 performance model
|
||||
- [ ] Wave 5 precision requirements from Wave 2/3 analysis
|
||||
- [ ] Wave 6 test plan covers findings from all prior waves
|
||||
- [ ] Wave 6 benchmarks compare against Wave 3 predictions
|
||||
- [ ] No contradictory findings between phases
|
||||
- [ ] Discoveries board used for cross-track sharing
|
||||
|
||||
---
|
||||
|
||||
## Quality Gates (Per-Wave)
|
||||
|
||||
| Wave | Phase | Gate Criteria | Required Tracks |
|
||||
|------|-------|--------------|-----------------|
|
||||
| 1 | Global Survey | Core model identified + architecture mapped + ≥1 KPI | 3/3 completed |
|
||||
| 2 | Theory | Key formulas LaTeX'd + convergence stated + complexity determined | 3/3 completed |
|
||||
| 3 | Algorithm | Pseudocode produced + stability assessed + performance predicted | ≥2/3 completed |
|
||||
| 4 | Module | Code-algorithm mapping + data structures reviewed + APIs documented | ≥2/3 completed |
|
||||
| 5 | Local | Hotspots identified + edge cases cataloged + precision risks flagged | ≥2/3 completed |
|
||||
| 6 | Integration | Test plan complete + benchmarks planned + QA report synthesized | 3/3 completed |
|
||||
|
||||
---
|
||||
|
||||
## Overall Quality Gates
|
||||
|
||||
| Gate | Threshold | Action |
|
||||
|------|-----------|--------|
|
||||
| PASS | >= 80% across all dimensions | Report ready for delivery |
|
||||
| REVIEW | 70-79% in any dimension | Flag dimension for improvement, user decides |
|
||||
| FAIL | < 70% in any dimension | Block delivery, identify gaps, suggest re-analysis |
|
||||
|
||||
---
|
||||
|
||||
## Issue Classification
|
||||
|
||||
### Errors (Must Fix)
|
||||
|
||||
- Missing governing equation identification (Wave 1)
|
||||
- LaTeX formulas with mathematical errors (Wave 2)
|
||||
- Algorithm pseudocode that doesn't match convergence requirements (Wave 3)
|
||||
- Code references to non-existent files/functions (Wave 4)
|
||||
- Unidentified catastrophic cancellation in critical path (Wave 5)
|
||||
- Test plan that doesn't cover identified stability issues (Wave 6)
|
||||
- Contradictory findings between phases
|
||||
- Missing context propagation (later phase ignores earlier findings)
|
||||
|
||||
### Warnings (Should Fix)
|
||||
|
||||
- Formulas without derivation steps
|
||||
- Convergence bounds stated without proof or reference
|
||||
- Missing edge case for known singularity
|
||||
- Performance model without memory bandwidth consideration
|
||||
- Data structure choice not justified
|
||||
- Test plan without manufactured solution verification
|
||||
- Benchmark without theoretical baseline comparison
|
||||
|
||||
### Notes (Nice to Have)
|
||||
|
||||
- Additional bibliography references
|
||||
- Alternative algorithm comparisons
|
||||
- Extended precision sensitivity analysis
|
||||
- Scaling prediction beyond current problem size
|
||||
- Code style or naming convention suggestions
|
||||
|
||||
---
|
||||
|
||||
## Severity Levels for Findings
|
||||
|
||||
| Severity | Definition | Example |
|
||||
|----------|-----------|---------|
|
||||
| **Critical** | Incorrect results or numerical failure | Wrong boundary condition → divergent solution |
|
||||
| **High** | Significant accuracy or performance degradation | Condition number 10^15 → double precision insufficient |
|
||||
| **Medium** | Suboptimal but functional | O(N^2) where O(N log N) is possible |
|
||||
| **Low** | Minor improvement opportunity | Unnecessary array copy in non-critical path |
|
||||
|
||||
---
|
||||
|
||||
## Document Quality Metrics
|
||||
|
||||
| Metric | Target | Measurement |
|
||||
|--------|--------|-------------|
|
||||
| Formula coverage | ≥ 90% of core equations in LaTeX | Count identified vs documented |
|
||||
| Code reference density | ≥ 1 file:line per finding | Count references per finding |
|
||||
| Cross-phase references | ≥ 3 per document (Waves 3-6) | Count cross-references |
|
||||
| Severity distribution | ≥ 1 per severity level | Count per level |
|
||||
| Discovery board contributions | ≥ 2 per track | Count NDJSON entries per worker |
|
||||
| Perspective package | Present in every document | Boolean per document |
|
||||
Reference in New Issue
Block a user