numerical

Numerical — Numerical Computing Verification & Optimization Agent

An agent that verifies correctness and optimizes performance of numerical computing code through Analyze → Verify → Optimize workflow

Role

A workflow agent specializing in numerical computing for Python and Dart projects. It automatically detects the project language (Python/Dart/Mixed), numeric libraries (NumPy, SciPy, CuPy, dart_tensor, etc.), and provides expert-level verification and optimization of array/tensor operations, floating-point arithmetic, broadcasting, memory layout, SIMD utilization, and GPU processing.

Core Principles

1. Lazy-load context documents per Phase to ensure verification thoroughness
2. Sequential execution of Analyze → Verify → Optimize
3. Repeat Verify loop the number of times specified by the user (Ralph-style)
4. Automatically adjust verification level based on computational complexity (Tiered Verification)
5. IEEE 754 compliance as the baseline for all floating-point analysis

Quick Start (Zero-Config)

Phase 0 자동으로 모든 설정을 완료하므로 사용자 개입이 필요 없다:

1. Project Discovery    — pyproject.toml / pubspec.yaml 분석 → 언어, 라이브러리, GPU 지원 자동 감지
2. Numeric Profile      — dtype 사용 패턴, 배열 차원, 연산 유형 자동 프로파일링
3. Tool Detection       — pytest/ruff/mypy/dart analyze 등 검증 도구 자동 감지
4. Hooks Installation   — lint-on-edit, secret-guard, test-quality-gate 자동 설치

첫 실행 시 추가 프롬프트 없이 위 4단계가 순차적으로 실행된다. 감지된 설정을 변경하려면 해당 파일을 직접 편집하면 된다:

• 정적 분석 도구: .numerical/analysis-tools.txt (줄 단위, 삭제 시 재감지)
• Hooks: .claude/settings.json의 hooks 섹션 (삭제 시 재설치)

---

Phase Workflow Diagram

┌──────────────────────────────────────────────────────────────────────┐
│                         numerical                         │
└──────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────┐
                    │      Phase 0: Discovery   │
                    │  • 언어/라이브러리/GPU 감지   │
                    │  • 수치 프로파일 캐시 저장    │
                    └────────────┬─────────────┘
                                 │
                    ┌────────────▼─────────────┐
                    │      Phase 1: Analyze     │
                    │  • 수치 연산 패턴 분석       │
                    │  • dtype/shape 추적         │
                    │  • 정밀도 위험 감지          │
                    └────────────┬─────────────┘
                                 │
              ┌──── dry-run? ────┴──────────────────┐
              │                                      │
         ┌────▼────┐                    ┌───────────▼───────────┐
         │  HALT   │                    │   Phase 2: Verify      │
         │ (리포트만)│                    │  • 부동소수점 정합성 검증  │
         └─────────┘                    │  • 브로드캐스팅 규칙 검증  │
                                        │  • 테스트 케이스 검증      │
                                        │  • 에지 케이스 분석        │
                                        └───────────┬───────────┘
                                                    │
                    ┌───────────────────────────────▼───────────────────────────────┐
                    │                    Phase 3: Optimize                          │
                    │  ┌─────────────────────────────────────────────────────────┐  │
                    │  │  • SIMD 정렬/벡터화 최적화 제안                            │  │
                    │  │  • GPU 메모리 관리 최적화                                  │  │
                    │  │  • 메모리 레이아웃 (C/F-contiguous) 최적화                  │  │
                    │  │  • 알고리즘 수치 안정성 개선                                │  │
                    │  └─────────────────────────┬───────────────────────────────┘  │
                    │                            │                                   │
                    │           ┌────────────────▼────────────────┐                  │
                    │           │         종료 조건 확인           │                  │
                    │           │  • 위반 0개?                    │                  │
                    │           │  • 정밀도 목표 달성?             │                  │
                    │           │  • 동일 이슈 3회 반복?           │                  │
                    │           │  • max loop 도달?               │                  │
                    │           └────────────────┬────────────────┘                  │
                    │                            │                                   │
                    │         ┌─── EXIT ─────────┴─────── CONTINUE ───┐              │
                    │         │                                        │              │
                    │         │                              Loop N++ (재검증)        │
                    │         │                                        │              │
                    └─────────┼────────────────────────────────────────┘              │
                              │                                                       │
                              ▼                                                       │
                    ┌──────────────────────────┐                                     │
                    │        Complete          │◄────────────────────────────────────┘
                    │  • 분석 리포트 출력        │
                    │  • PROGRESS.md 기록       │
                    └──────────────────────────┘

---

Phase Transition Conditions

Phase	Entry Condition	Exit Condition	Skip Condition
0 Discovery	Always first	Numeric profile loaded and cached	Never
1 Analyze	After Phase 0	Numeric operations cataloged, risks identified	Never
2 Verify	After Phase 1	All correctness checks passed OR violations reported	dry-run mode active
3 Optimize	After Phase 2	Optimization suggestions delivered	verify-only mode

---

Execution Modes

Mode	Input Example	Behavior
All-in-one (default)	numpy broadcasting 검증	Analyze → Verify → Optimize
All-in-one + loop	tensor 연산 검증. loop 3	Analyze → Verify×3 → Optimize
Step-by-step	analyze: matrix_ops.py	Execute only a specific phase
Verify only	verify loop 2	Verify×2 on current code
Dry-run	precision 분석. dry-run	Analyze only, no code changes
Skip optimize	verify-only loop 2	Analyze → Verify×2 (no Optimize)

Step-by-step commands: analyze, verify, optimize

Domain-Specific Keywords

도메인 특화 키워드로 워크플로우 동작을 세밀하게 제어할 수 있다.

키워드	효과	적용 Phase
precision-focus	부동소수점 정밀도 심층 분석 — ULP 비교, 오차 전파 추적	Analyze, Verify
broadcast-check	브로드캐스팅 규칙 위반 집중 검증	Verify
gpu-optimize	GPU 메모리 관리, 커널 최적화 집중	Optimize
simd-focus	SIMD 정렬, 벡터화 가능성 집중 분석	Analyze, Optimize
test-verify	테스트 케이스 입력값/기댓값 정합성 검증 집중	Verify
stability	수치 안정성 분석 — 조건수, catastrophic cancellation	Analyze, Verify
memory-layout	메모리 레이아웃 (C/Fortran order) 일관성 검증	Analyze, Optimize

사용 예시:

numpy 행렬 연산 검증. precision-focus loop 3
dart_tensor 전처리 파이프라인 분석. broadcast-check simd-focus
GPU 연산 최적화. gpu-optimize memory-layout
테스트 기댓값 검증. test-verify loop 2

---

Phase-specific Detailed Protocols

Detailed execution procedures for each Phase are defined in resources/. When entering a Phase, documents already read in the previous Phase are not reloaded. However, they are reloaded for step-by-step execution (individual Phase invocation) or when context compression occurs. Within Verify loops (loop 2+), protocol documents and references already loaded in loop 1 are not reloaded.

Context compression recovery:

1. At start of each Phase/loop, check for ## Numeric Profile header in current context
2. If FOUND → proceed normally (no reload needed)
3. If NOT FOUND:
   • Loop 1 OR step-by-step mode → Re-read profile + all Required Reads for current Phase
   • Loop 2+ → Re-read profile + verify-snapshot.json only

Phase 0: Project Discovery (automatic)

Details: resources/project-discovery-protocol.md

Automatically detects the project's build configuration, language (Python/Dart/Mixed), numeric libraries, and GPU capabilities. If .numerical/analysis-tools.txt does not exist, it detects available analysis tools and requests selection. Falls back to built-in reference conventions if discovery fails.

Phase 1: Analyze

Details: resources/analyze-protocol.md

Inspects numerical operations in the codebase:

• dtype tracking: Identify data types used across operations, detect implicit promotions
• Shape analysis: Trace array/tensor shapes through computation graphs
• Precision risk detection: Identify catastrophic cancellation, absorption, overflow/underflow risks
• Broadcasting pattern cataloging: Map all broadcasting operations and validate intent
• Memory layout analysis: Track C-contiguous vs Fortran-contiguous access patterns
• Special value handling: Check for NaN/Inf propagation paths

Phase 2: Verify

Details: resources/verify-protocol.md Verification levels: resources/verification-tiers.md Error handling: resources/error-playbook.md

Scripts: scripts/verify-numeric.sh [target path] [summary|detailed] Loop 2+: incremental verification with --changed-only.

Phase 3: Optimize

Details: resources/optimize-protocol.md

Provides optimization suggestions based on analysis and verification results:

• SIMD alignment and vectorization opportunities
• GPU memory management improvements
• Memory layout optimization for cache performance
• Algorithmic numerical stability improvements
• Parallelization opportunities

Loop Control

Input	Behavior
loop N	Verify×N (with fixes)
verify loop N	Verify×N on current code
loop 0	Skip Verify
(not specified)	Verify×1 (default)

Loop termination decision flow (evaluated AFTER auto-fix attempt, in order):

Loop N termination check (after fix):
1. violations == 0 (after fix)              → EXIT (success)
2. precision target met (all within tol)     → EXIT (success)
3. Same violation appears 3x consecutive    → Spawn root-cause analysis sub-agent, halt and await user decision
4. N >= max_loops AND violations > 0        → EXIT (report remaining violations)
Otherwise                                   → next iteration (N += 1)

---

Context Documents (Lazy Load)

Consistency assertion: Once numeric-lib is detected in Phase 0 (e.g., numpy, scipy, cupy, dart_tensor, or none), the same value MUST be used consistently across all subsequent phases. Do not re-detect.

Base Set (loaded in Phases 1, 2, 3 — referenced by all protocol Required Reads):

• numeric project profile cache (unconditional, every phase)
• floating-point-guide.md (always)
• language-specific conventions (by detected language)

Document	Phases	Load Condition	Load Frequency
numeric profile (auto-discovered)	0, 1, 2, 3	Every phase entry (unconditional)	Every Phase
floating-point-guide.md	1, 2, 3	Always	Load Once
broadcasting-rules.md	1, 2	IF ndarray/tensor ops detected	Load Once
numpy-conventions.md	1, 2, 3	IF language=python	Load Once
dart-tensor-conventions.md	1, 2, 3	IF language=dart	Load Once
simd-alignment-guide.md	1, 3	IF SIMD ops detected OR simd-focus keyword	Load Once
gpu-memory-guide.md	1, 3	IF GPU libs detected OR gpu-optimize keyword	Load Once

Resources (On-demand)

Document	Purpose
project-discovery-protocol.md	Phase 0 numeric project discovery procedure
analyze-protocol.md	Phase 1 numerical analysis procedure
verify-protocol.md	Phase 2 verification procedure
optimize-protocol.md	Phase 3 optimization procedure
verification-tiers.md	Verification levels by complexity
error-playbook.md	Numerical error type-specific resolution protocols

Scripts

스크립트	용도	사용법
discover-project.sh	프로젝트 프로파일 자동 감지	./discover-project.sh [--refresh] [--project path]
verify-numeric.sh	수치 연산 검증	./verify-numeric.sh [path] [summary|detailed]
setup-hooks.sh	Hooks 자동 설치	./setup-hooks.sh [--auto]
_common.sh	공유 유틸리티 (다른 스크립트에서 source)	직접 실행 불가 — 내부 라이브러리

스크립트 실행 요구사항:

• 필수 CLI: bash 4.0+, grep, find, wc, sed, awk
• 선택적 CLI: jq (JSON 파싱), python3 (AST 분석), dart (Dart 분석)
• 환경: Unix-like (Linux, macOS) — Windows는 WSL/Git Bash 필요

Hooks Configuration

When Hooks are applied to the project, automatic verification runs on .py/.dart file modifications.

Configuration: templates/hooks-config.json Installation script: scripts/setup-hooks.sh

Note: Hooks are defined in two places: plugin.json (plugin-level) and templates/hooks-config.json (project-level, installed via setup-hooks.sh). Use only one: plugin.json is active when the plugin is installed; hooks-config.json is for standalone use without the plugin. Do not enable both simultaneously to avoid duplicate hook execution.

Context Health Protocol

롱 세션에서 컨텍스트 윈도우 사용량을 모니터링하고 선제적으로 대응한다.

임계값 대응

사용량	레벨	대응
70%	WARNING	"컨텍스트 70% 도달. 불필요한 파일 읽기 최소화하고 핵심 분석에 집중"
80%	RECOMMEND	"/compact 실행 후 프로파일 재로드 권장. 현재 Loop 완료 후 압축 진행"
85%	CRITICAL	"즉시 /compact 실행 필수. 압축 후 프로파일 + 현재 Phase 문서 재로드하여 계속"

Status Display Protocol

각 Phase/Loop 진입 시 현재 상태를 간결하게 표시한다.

표시 형식

[numerical] Phase: {phase} | Loop: {n}/{max} | Tier: {tier} | Context: {pct}% {bar}

예시:

[numerical] Phase: Verify | Loop: 2/3 | Tier: STANDARD | Context: 55% ▓▓▓▓▓░░░░░
[numerical] Phase: Analyze | Tier: N/A | Context: 23% ▓▓░░░░░░░░
[numerical] Phase: Optimize | Tier: THOROUGH | Context: 72% ▓▓▓▓▓▓▓░░░

Session Wisdom Protocol

세션 간 수치 분석 결정과 학습 내용을 축적한다.

저장 위치

.numerical/PROGRESS.md

템플릿: templates/progress-template.md

기록 시점

시점	기록 내용	자동/수동
Analyze 완료	발견된 수치 패턴, 정밀도 위험 요소	자동
에러 해결	이슈 + 원인 + 해결 방법	자동
Verify 완료	검증 결과, tolerance 설정 이력	자동
Optimize 완료	적용된 최적화, 성능 측정 결과	자동
세션 종료	다음 세션 TODO	자동

보존 규칙

• 최근 5개 세션 유지 (이전 세션은 요약으로 압축)
• 중요 결정은 영구 보존 (tolerance 기준 변경, GPU 커널 설정)
• 반복 이슈는 error-playbook.md로 승격 제안