From 6157fd3d7b03231c6779bc971686c5e66e8a815e Mon Sep 17 00:00:00 2001
From: Sridhar Ratnakumar <srid@srid.ca>
Date: Sat, 21 Mar 2026 12:45:59 -0400
Subject: [PATCH] Add /elegance command; enhance /factually with architecture &
 self-sufficient phases

Closes #109, closes #110
---
 AI/commands/elegance.md  | 60 ++++++++++++++++++++++++++++++++++++++++
 AI/commands/factually.md |  6 ++++
 2 files changed, 66 insertions(+)
 create mode 100644 AI/commands/elegance.md

diff --git a/AI/commands/elegance.md b/AI/commands/elegance.md
new file mode 100644
index 0000000..1f31b28
--- /dev/null
+++ b/AI/commands/elegance.md
@@ -0,0 +1,60 @@
+---
+description: Iteratively simplify & beautify code — research elegance, apply, verify, repeat
+argument-hint: "<tech> [iterations=3]"
+disable-model-invocation: true
+---
+
+# Elegance Command
+
+Iteratively study and apply elegant coding patterns to the codebase for **$0**. Each iteration: understand the code, research what simple & elegant code looks like, apply learnings, verify with CI.
+
+Run for **$1** iterations (default: 3). The value can be a number (e.g., `3`) or a duration (e.g., `2h`).
+
+## Workflow
+
+### 0. **Determine Scope**
+
+   - Before starting, use the `AskUserQuestion` tool to ask: should this operate on the **whole codebase** or only on **changes in the current branch/PR**?
+   - If scoped to current branch/PR, use `git diff main...HEAD` (or the appropriate base branch) to identify changed files and limit all subsequent steps to those files only.
+
+### For each iteration (1 to N):
+
+#### 1. **Understand the Codebase**
+
+   - Read through the relevant source files for $0.
+   - Note patterns, repetition, unnecessary complexity, non-idiomatic code.
+
+#### 2. **Research Elegant Patterns**
+
+   - Use WebSearch/WebFetch to research what simple, elegant (yet readable!) $0 code looks like.
+   - Look for idiomatic patterns, standard simplifications, and community best practices.
+   - Focus on: simplicity, readability, removing unnecessary abstraction, leveraging language features.
+
+#### 3. **Apply Learnings**
+
+   - Refactor the codebase based on what you learned.
+   - This can include: edits, code reorganization, or even rewrites where simplicity demands it.
+   - Prefer fewer lines, clearer intent, and idiomatic style.
+   - Don't add unnecessary abstractions — remove them.
+
+#### 4. **Verify**
+
+   - Run local CI to check your edits: `nix run github:juspay/vira -- ci -b`
+   - If CI fails, fix the issues before proceeding to the next iteration.
+
+#### 5. **Log Progress**
+
+   - Briefly note what changed in this iteration and why.
+
+### After all iterations:
+
+- Do **not** git commit. Leave all changes in the working directory for the user to review.
+- Present a summary of what changed across all iterations.
+
+## Principles
+
+- **Simple over clever**: Elegant code is simple code.
+- **Readable over terse**: Brevity is good, but not at the cost of clarity.
+- **Well-commented**: Add comments where code isn't self-explanatory. An unsuspecting third-party programmer should be able to understand every non-obvious decision. Don't comment the obvious — comment the *why*.
+- **Idiomatic over generic**: Use the language's strengths. Write TypeScript like TypeScript, not like Java.
+- **Each iteration builds on the last**: Don't undo previous improvements. Deepen them.
diff --git a/AI/commands/factually.md b/AI/commands/factually.md
index 9832866..6a44c1d 100644
--- a/AI/commands/factually.md
+++ b/AI/commands/factually.md
@@ -39,12 +39,18 @@ Respond to the user's prompt using Plan mode, grounded in thorough research rath
    - Focus on **architecture and approach** — the "shape" of the solution.
    - **Prefer simplicity**: if two approaches exist and one is simpler, choose it. Justify complexity only when necessary.
    - Call out trade-offs and alternatives considered, briefly.
+   - **Include an Architecture section** in the plan that covers:
+     - What modules/components are affected and how they relate
+     - Architectural-level changes, impact, and considerations
+     - Any new abstractions, interfaces, or boundaries being introduced or modified
+     - Potential ripple effects on the rest of the system
 
 ### 5. **Split Non-Trivial Plans into Phases**
 
    - If the plan is non-trivial, break it into small, sequential phases.
    - **MVP first**: Phase 1 should deliver the minimum viable version. Later phases layer on.
    - Each phase should be small enough for the human to review every line of code.
+   - **Each phase must be functionally self-sufficient**: after completing any phase, the system should work end-to-end. Don't split by layer (e.g., client/server/tests separately) — instead split by feature slice so each phase delivers a working whole.
    - One phase = one focused concern. Don't mix unrelated changes.
 
 ### 6. **Present Plan for Feedback**