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
@@ -0,0 +1,179 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user