add-rule

# Add Rule Step-by-step guide for adding a transformation/mapping between two existing concepts. ## Step 0: Gather Required Information | # | Item | Description | |---|------|-------------| | 1 | **Source** | What is being transformed FROM (must exist) | | 2 | **Target** | What is being transformed TO (must exist) | | 3 | **Algorithm** | How to transform source → target | | 4 | **Inverse mapping** | How to map target solution back to source (if applicable) | | 5 | **Correctness argument** | Why the transformation preserves correctness/optimality | | 6 | **Concrete example** | A small worked-out instance (tutorial style) | | 7 | **Reference** | Paper, documentation, or URL | | 8 | **Reference implementation** | Existing rule/transform to use as template | Put a high standard on item 6 — it must be tutorial style with clear intuition. Do NOT proceed until complete. ## Step 1: Study Reference Implementation Read the reference transformation. Understand: - Source → target mapping structure - Inverse mapping / solution extraction pattern - Registration mechanism - Test pattern (especially closed-loop testing) ## Step 2: Implement the Transformation 1. Create source file following project naming convention 2. Implement forward mapping (source → target) 3. Implement inverse mapping (target solution → source solution), if applicable 4. Register via project mechanism (macros, decorators, config, etc.) ## Step 3: Write Tests Required: **closed-loop test**: 1. Create source instance 2. Transform to target 3. Solve target 4. Extract/map back to source 5. Verify: result is valid and correct for source Additional: edge cases, empty inputs, identity transforms. ## Step 4: Write Example Create an example program demonstrating the transformation: - Use the concrete example from Step 0 - Show source → target → solve → extract → verify - Register in project's example/test harness ## Step 5: Document Update project documentation with: - Transformation description - Correctness argument - Example walkthrough ## Step 6: Verify Run project test and lint commands, then invoke `workflow:review-implementation`. ## Common Mistakes | Mistake | Fix | |---------|-----| | Missing inverse mapping state | Store any index maps needed for solution extraction | | No closed-loop test | Always test the full round-trip | | Example not registered | Must be runnable by project test harness | | Skipping correctness argument | Transformations without proof are bugs waiting to happen |