diff --git a/commands/agent-os/algorithm-drift.md b/commands/agent-os/algorithm-drift.md new file mode 100644 index 00000000..137b0852 --- /dev/null +++ b/commands/agent-os/algorithm-drift.md @@ -0,0 +1,179 @@ +# Algorithm Drift + +Detect drift between algorithm documentation and implementation code. + +This command compares an algorithm spec in `agent-os/standards/algorithms/` against its owned implementation files to find mismatches in conventions, parameters, or structure. + +--- + +## When to Use + +- After modifying algorithm implementation code +- Before major refactors of mathematical code +- When debugging convention-related bugs (wrong frames, units, quaternions) +- Periodic sync checks for algorithm-heavy projects + +--- + +## Process + +### Step 1: Identify the Algorithm + +If the user specifies an algorithm name (e.g., `/algorithm-drift ekf`), use it directly. + +If no name provided, list available algorithms: + +```bash +ls agent-os/standards/algorithms/*.md +``` + +Use `AskUserQuestion` to let user select which algorithm to check. + +### Step 2: Read the Algorithm Spec + +Read the algorithm spec file at `agent-os/standards/algorithms/{name}.md`. + +Parse the frontmatter to extract the `owns:` field listing implementation files. + +**owns: field rules:** +- Paths are relative to project root +- Globs are supported (e.g., `src/filters/*.py`) +- If a file is missing, report as warning (not error) + +### Step 3: Read Owned Implementation Files + +For each path in `owns:`: +- Expand globs if present +- Read each file +- If file missing, note it as warning + +### Step 4: Compare Spec vs Code + +Analyze for four types of drift: + +1. **Structural drift**: Functions present/missing, different step order than spec +2. **Parameter drift**: Different I/O signatures, changed constants +3. **Mathematical drift**: Different equations, changed conventions (frames, quaternions, units) +4. **Implementation drift**: Refactored code, new files not listed in `owns:` + +Focus especially on the **Conventions** section — this is where silent bugs hide. + +### Step 5: Report Findings + +If no drift detected: +``` +No drift detected in agent-os/standards/algorithms/{name}.md + +Checked files: +- src/filters/ekf.ts (ok) +- src/filters/ekf.test.ts (ok) +``` + +If drift detected: +``` +Drift detected in agent-os/standards/algorithms/{name}.md: + +- Conventions: Spec says Hamilton quaternions, code uses JPL (src/filters/ekf.ts:45) +- Parameters: Spec says Q=0.1, code has Q=0.01 (src/filters/ekf.ts:78) +- Structural: Function `predict()` in spec not found in code + +Warnings: +- File src/filters/ekf.test.ts not found +``` + +### Step 6: Offer Resolution + +Use `AskUserQuestion` to present options: + +1. **Update spec to match code** — Code is correct, spec is outdated +2. **Update code to match spec** — Spec is correct, code drifted +3. **Review manually** — Need to investigate further + +Execute the chosen option or provide guidance for manual review. + +--- + +## Algorithm Doc Template + +When creating new algorithm docs, use this template: + +```markdown +--- +owns: + - path/to/impl.py + - path/to/impl.cpp +--- + +# [Algorithm Name] + +## Purpose + +[What this solves. Where it fits in the system.] + +## I/O + +**Inputs:** +- `name` (type/shape): description [units/frame if applicable] + +**Outputs:** +- `name` (type/shape): description [units/frame if applicable] + +## Conventions + +[Domain-specific conventions that affect correctness: +coordinate frames, rotation conventions, tensor layouts, sign conventions, etc.] + +## Diagram + +[Required. Visual representation of the algorithm flow. + +Choose the style that best fits: +- Pipeline: A → B → C → D +- Architecture: Layered boxes +- Flowchart: Branches and decisions +- Data flow: Variable transformations +- Math flow: Equations connected by arrows] + +## Method + +[High-level description of the approach.] + +### Step 1: [Name] + +[Description with equations, variables, implementation hints as needed.] + +### Step 2: [Name] + +[Continue for each major step...] + +--- + +## Implementation + +[How spec maps to code: +- File structure and key functions +- Function → Step mapping +- Key constants and rationale] + +## Notes + +[Invariants, edge cases, validation approaches, known limitations.] +``` + +--- + +## Output Location + +Algorithm specs: `agent-os/standards/algorithms/{name}.md` + +After creating or updating specs, run `/index-standards` to update the index. + +--- + +## Tips + +- **Conventions section is critical** — This is where quaternion bugs, frame mismatches, and unit errors hide +- **Diagram is required** — Visual representation helps catch structural drift +- **owns: field enables drift detection** — Keep it updated when refactoring +- **Run periodically** — Drift accumulates silently over time +- **Check before releases** — Especially for safety-critical algorithms diff --git a/commands/agent-os/discover-standards.md b/commands/agent-os/discover-standards.md index b5de63ee..3e412003 100644 --- a/commands/agent-os/discover-standards.md +++ b/commands/agent-os/discover-standards.md @@ -21,6 +21,7 @@ If no area was specified: - **Frontend areas:** UI components, styling/CSS, state management, forms, routing - **Backend areas:** API routes, database/models, authentication, background jobs - **Cross-cutting:** Error handling, validation, testing, naming conventions, file structure + - **Algorithms:** Filters, controllers, solvers, estimators, ML models, training loops, numerical methods, signal processing (use algorithm template — see "Discovering Algorithms" section below) 3. Use AskUserQuestion to present the areas: ``` @@ -30,6 +31,7 @@ I've identified these areas in your codebase: 2. **Database** (src/models/, src/db/) — Models, queries, migrations 3. **React Components** (src/components/) — UI patterns, props, state 4. **Authentication** (src/auth/) — Login, sessions, permissions +5. **Algorithms** (src/filters/, src/control/) — Filters, controllers, solvers Which area should we focus on for discovering standards? (Pick one, or suggest a different area) ``` @@ -91,6 +93,7 @@ For each standard (after completing Step 3's Q&A): 1. Determine the appropriate folder (create if needed): - `api/`, `database/`, `javascript/`, `css/`, `backend/`, `testing/`, `global/` + - `algorithms/` — For algorithmic/mathematical code (see "Discovering Algorithms" section) 2. Check if a related standard file already exists — append to it if so @@ -158,6 +161,103 @@ Standards created for [area]: Would you like to discover standards in another area, or are we done? ``` +--- + +## Discovering Algorithms + +When the user selects "Algorithms" as the focus area, use a different flow. Algorithm documentation requires more structure to prevent convention bugs in mathematical/computational code. + +### Algorithm Step 1: Identify Algorithms + +Scan for algorithmic patterns: +- Filters, estimators, state estimation +- Controllers, planners, optimizers, solvers +- ML models, training loops, loss functions +- Numerical methods, simulations +- Signal processing, transforms +- Kinematics, dynamics + +Present findings: + +``` +I found these potential algorithms in your codebase: + +1. **EKF** (src/filters/ekf.cpp, src/filters/ekf.h) — State estimation filter +2. **QP Solver** (src/control/qp_solver.py) — Quadratic programming optimization +3. **CNN Classifier** (src/models/classifier.py, src/models/layers.py) — Image classification + +Which would you like to document? +``` + +### Algorithm Step 2: For Each Algorithm, Ask High-Level Questions + +Follow the algorithm template structure. Ask about: + +1. **Purpose**: "What does this algorithm do? What problem does it solve?" + +2. **I/O**: "What are the inputs and outputs? What are their types, shapes, units?" + +3. **Files (owns:)**: "Which files implement this algorithm? (I found: src/filters/ekf.cpp, src/filters/ekf.h — are there others?)" + +4. **Conventions**: "Are there domain-specific conventions that affect correctness?" + - This is open-ended — don't assume. Could be: + - Coordinate frames (robotics) + - Quaternion conventions (robotics, graphics) + - Tensor layouts (ML) + - Units (scientific) + - Sign conventions (control systems) + - If user says none, that's fine + +5. **Method**: "What are the key steps of this algorithm?" + +### Algorithm Step 3: Create Algorithm File + +Use the algorithm template (embedded in `/algorithm-drift` command): + +```markdown +--- +owns: + - src/filters/ekf.cpp + - src/filters/ekf.h +--- + +# Extended Kalman Filter + +## Purpose +[From user's answer] + +## I/O +**Inputs:** +- [From user's answer with types/units] + +**Outputs:** +- [From user's answer with types/units] + +## Conventions +[From user's answer, or "None identified" if not applicable] + +## Diagram +[Generate based on method description] + +## Method +[From user's answer, structured as steps] + +## Implementation +- `ekf.cpp` — Main filter implementation +- `ekf.h` — State and covariance types + +## Notes +[Any edge cases, invariants, or validation notes from discussion] +``` + +Create in `agent-os/standards/algorithms/{name}.md` + +### Algorithm Step 4: Continue + +Repeat for each selected algorithm, then update index as usual. + +--- + ## Output Location All standards: `agent-os/standards/[folder]/[standard].md` diff --git a/standards/algorithms/.gitkeep b/standards/algorithms/.gitkeep new file mode 100644 index 00000000..e69de29b