ai-devkit 0.12.0 → 0.14.0

package/dist/templates/templates/commands/code-review.md

@@ -1,85 +1,11 @@
 ---
-description: Perform a local code review before pushing changes, ensuring alignment with design docs and best practices.
+description: Pre-push code review against design docs.
 ---
 
-# Local Code Review Assistant
+Perform a local code review **before** pushing changes.
 
-You are helping me perform a local code review **before** I push changes. Please follow this structured workflow.
-
-## Step 1: Gather Context
-Ask me for:
-- Brief feature/branch description
-- List of modified files (with optional summaries)
-- Relevant design doc(s) (e.g., `docs/ai/design/feature-{name}.md` or project-level design)
-- Any known constraints or risky areas
-- Any open bugs or TODOs linked to this work
-- Which tests have already been run
-
-If possible, request the latest diff:
-```bash
-git status -sb
-git diff --stat
-```
-
-## Step 2: Understand Design Alignment
-For each provided design doc:
-- Summarize the architectural intent
-- Note critical requirements, patterns, or constraints the design mandates
-
-## Step 3: File-by-File Review
-For every modified file:
-1. Highlight deviations from the referenced design or requirements
-2. Spot potential logic or flow issues and edge cases
-3. Identify redundant or duplicate code
-4. Suggest simplifications or refactors (prefer clarity over cleverness)
-5. Flag security concerns (input validation, secrets, auth, data handling)
-6. Check for performance pitfalls or scalability risks
-7. Ensure error handling, logging, and observability are appropriate
-8. Note any missing comments or docs
-9. Flag missing or outdated tests related to this file
-
-## Step 4: Cross-Cutting Concerns
-- Verify naming consistency and adherence to project conventions
-- Confirm documentation/comments are updated where the behavior changed
-- Identify missing tests (unit, integration, E2E) needed to cover the changes
-- Ensure configuration/migration updates are captured if applicable
-
-## Step 5: Summarize Findings
-Provide results in this structure:
-```
-### Summary
-- Blocking issues: [count]
-- Important follow-ups: [count]
-- Nice-to-have improvements: [count]
-
-### Detailed Notes
-1. **[File or Component]**
-   - Issue/Observation: ...
-   - Impact: (e.g., blocking / important / nice-to-have)
-   - Recommendation: ...
-   - Design reference: [...]
-
-2. ... (repeat per finding)
-
-### Recommended Next Steps
-- [ ] Address blocking issues
-- [ ] Update design/implementation docs if needed
-- [ ] Add/adjust tests:
-      - Unit:
-      - Integration:
-      - E2E:
-- [ ] Rerun local test suite
-- [ ] Re-run code review command after fixes
-```
-
-## Step 6: Final Checklist
-Confirm whether each item is complete (yes/no/needs follow-up):
-- Implementation matches design & requirements
-- No obvious logic or edge-case gaps remain
-- Redundant code removed or justified
-- Security considerations addressed
-- Tests cover new/changed behavior
-- Documentation/design notes updated
-
----
-Let me know when you're ready to begin the review.
+1. **Gather Context** — If not already provided, ask for: feature/branch description, list of modified files, relevant design doc(s) (e.g., `docs/ai/design/feature-{name}.md`), known constraints or risky areas, and which tests have been run. Also review the latest diff via `git status` and `git diff --stat`.
+2. **Understand Design Alignment** — For each design doc, summarize architectural intent and critical constraints.
+3. **File-by-File Review** — For every modified file: check alignment with design/requirements and flag deviations, spot logic issues/edge cases/redundant code, flag security concerns (input validation, secrets, auth, data handling), check error handling/performance/observability, and identify missing or outdated tests.
+4. **Cross-Cutting Concerns** — Verify naming consistency and project conventions. Confirm docs/comments updated where behavior changed. Identify missing tests (unit, integration, E2E). Check for needed configuration/migration updates.
+5. **Summarize Findings** — Categorize each finding as **blocking**, **important**, or **nice-to-have** with: file, issue, impact, recommendation, and design reference.

package/dist/templates/templates/commands/debug.md

@@ -1,49 +1,11 @@
 ---
-description: Guide me through debugging a code issue by clarifying expectations, identifying gaps, and agreeing on a fix plan before changing code.
+description: Debug an issue with structured root-cause analysis before changing code.
 ---
 
-# Local Debugging Assistant
-
-Help me debug an issue by clarifying expectations, identifying gaps, and agreeing on a fix plan before changing code.
-
-## Step 1: Gather Context
-Ask me for:
-- Brief issue description (what is happening?)
-- Expected behavior or acceptance criteria (what should happen?)
-- Current behavior and any error messages/logs
-- Recent related changes or deployments
-- Scope of impact (users, services, environments)
-
-## Step 2: Clarify Reality vs Expectation
-- Restate the observed behavior vs the expected outcome
-- Confirm relevant requirements, tickets, or docs that define the expectation
-- Identify acceptance criteria for the fix (how we know it is resolved)
-
-## Step 3: Reproduce & Isolate
-- Determine reproducibility (always, intermittent, environment-specific)
-- Capture reproduction steps or commands
-- Note any available tests that expose the failure
-- List suspected components, services, or modules
-
-## Step 4: Analyze Potential Causes
-- Brainstorm plausible root causes (data, config, code regressions, external dependencies)
-- Gather supporting evidence (logs, metrics, traces, screenshots)
-- Highlight gaps or unknowns that need investigation
-
-## Step 5: Surface Options
-- Present possible resolution paths (quick fix, deeper refactor, rollback, feature flag, etc.)
-- For each option, list pros/cons, risks, and verification steps
-- Consider required approvals or coordination
-
-## Step 6: Confirm Path Forward
-- Ask which option we should pursue
-- Summarize chosen approach, required pre-work, and success criteria
-- Plan validation steps (tests, monitoring, user sign-off)
-
-## Step 7: Next Actions & Tracking
-- Document tasks, owners, and timelines for the selected option
-- Note follow-up actions after deployment (monitoring, comms, postmortem if needed)
-- Encourage updating relevant docs/tests once resolved
-
-Let me know when you're ready to walk through the debugging flow.
+Help me debug an issue. Clarify expectations, identify gaps, and agree on a fix plan before changing code.
 
+1. **Gather Context** — If not already provided, ask for: issue description (what is happening vs what should happen), error messages/logs/screenshots, recent related changes or deployments, and scope of impact.
+2. **Clarify Reality vs Expectation** — Restate observed vs expected behavior. Confirm relevant requirements or docs that define the expectation. Define acceptance criteria for the fix.
+3. **Reproduce & Isolate** — Determine reproducibility (always, intermittent, environment-specific). Capture reproduction steps. List suspected components or modules.
+4. **Analyze Potential Causes** — Brainstorm root causes (data, config, code regressions, external dependencies). Gather supporting evidence (logs, metrics, traces). Highlight unknowns needing investigation.
+5. **Resolve** — Present resolution options (quick fix, refactor, rollback, etc.) with pros/cons and risks. Ask which option to pursue. Summarize chosen approach, pre-work, success criteria, and validation steps.

package/dist/templates/templates/commands/execute-plan.md

@@ -1,75 +1,11 @@
 ---
-description: Execute a feature plan interactively, guiding me through each task while referencing relevant docs and updating status.
+description: Execute a feature plan task by task.
 ---
 
-# Feature Plan Execution Assistant
-
 Help me work through a feature plan one task at a time.
 
-## Step 1: Gather Context
-Ask me for:
-- Feature name (kebab-case, e.g., `user-authentication`)
-- Brief feature/branch description
-- Relevant planning doc path (default `docs/ai/planning/feature-{name}.md`)
-- Any supporting design/implementation docs (design, requirements, implementation)
-- Current branch and latest diff summary (`git status -sb`, `git diff --stat`)
-
-## Step 2: Load the Plan
-- Request the planning doc contents or offer commands like:
-  ```bash
-  cat docs/ai/planning/feature-<name>.md
-  ```
-- Parse sections that represent task lists (look for headings + checkboxes `[ ]`, `[x]`).
-- Build an ordered queue of tasks grouped by section (e.g., Foundation, Core Features, Testing).
-
-## Step 3: Present Task Queue
-Show an overview:
-```
-### Task Queue: <Feature Name>
-1. [status] Section • Task title
-2. ...
-```
-Status legend: `todo`, `in-progress`, `done`, `blocked` (based on checkbox/notes if present).
-
-## Step 4: Interactive Task Execution
-For each task in order:
-1. Display the section/context, full bullet text, and any existing notes.
-2. Suggest relevant docs to reference (requirements/design/implementation).
-3. Ask: "Plan for this task?" Offer to outline sub-steps using the design doc.
-4. Prompt to mark status (`done`, `in-progress`, `blocked`, `skipped`) and capture short notes/next steps.
-5. Encourage code/document edits inside Cursor; offer commands/snippets when useful.
-6. If blocked, record blocker info and move task to the end or into a "Blocked" list.
-
-## Step 5: Update Planning Doc
-After each status change, generate a Markdown snippet the user can paste back into the planning doc, e.g.:
-```
-- [x] Task: Implement auth service (Notes: finished POST /auth/login, tests added)
-```
-Remind the user to keep the source doc updated.
-
-## Step 6: Check for Newly Discovered Work
-After each section, ask if new tasks were discovered. If yes, capture them in a "New Work" list with status `todo` and include in the summary.
-
-## Step 7: Session Summary
-Produce a summary table:
-```
-### Execution Summary
-- Completed: (list)
-- In Progress: (list + owners/next steps)
-- Blocked: (list + blockers)
-- Skipped / Deferred: (list + rationale)
-- New Tasks: (list)
-```
-
-## Step 8: Next Actions
-Remind the user to:
-- Update `docs/ai/planning/feature-{name}.md` with the new statuses
-- Sync related docs (requirements/design/implementation/testing) if decisions changed
-- Run `/check-implementation` to validate changes against design docs
-- Run `/writing-test` to produce unit/integration tests targeting 100% coverage
-- Run `/update-planning` to reconcile the planning doc with the latest status
-- Run `/code-review` when ready for final review
-- Run test suites relevant to completed tasks
-
----
-Let me know when you're ready to start executing the plan. Provide the feature name and planning doc first.
+1. **Gather Context** — If not already provided, ask for: feature name (kebab-case, e.g., `user-authentication`), brief feature/branch description, planning doc path (default `docs/ai/planning/feature-{name}.md`), and any supporting docs (design, requirements, implementation).
+2. **Load & Present Plan** — Read the planning doc and parse task lists (headings + checkboxes). Present an ordered task queue grouped by section, with status: `todo`, `in-progress`, `done`, `blocked`.
+3. **Interactive Task Execution** — For each task in order: display context and full bullet text, reference relevant design/requirements docs, offer to outline sub-steps before starting, prompt for status update (`done`, `in-progress`, `blocked`, `skipped`) with short notes after work, and if blocked record blocker and move to a "Blocked" list.
+4. **Update Planning Doc** — After each status change, generate a markdown snippet to paste back into the planning doc. After each section, ask if new tasks were discovered.
+5. **Session Summary** — Produce a summary: Completed, In Progress (with next steps), Blocked (with blockers), Skipped/Deferred, and New Tasks. Remind to update `docs/ai/planning/feature-{name}.md` and sync related docs if decisions changed.

package/dist/templates/templates/commands/new-requirement.md

@@ -1,131 +1,18 @@
 ---
-description: Add new feature/requirement documentation and guide me through the development workflow from requirements to testing.
+description: Scaffold feature documentation from requirements through planning.
 ---
 
-I want to add a new feature/requirement. Please guide me through the complete development workflow:
-
-## Step 1: Capture Requirement
-First, ask me:
-- What is the feature name? (e.g., "user-authentication", "payment-integration")
-- What problem does it solve?
-- Who will use it?
-- What are the key user stories?
-
-## Step 2: Create Feature Documentation Structure
-Once I provide the requirement, create the following files (copy the existing template content so sections/frontmatter match exactly):
-- Start from `docs/ai/requirements/README.md` → save as `docs/ai/requirements/feature-{name}.md`
-- Start from `docs/ai/design/README.md` → save as `docs/ai/design/feature-{name}.md`
-- Start from `docs/ai/planning/README.md` → save as `docs/ai/planning/feature-{name}.md`
-- Start from `docs/ai/implementation/README.md` → save as `docs/ai/implementation/feature-{name}.md`
-- Start from `docs/ai/testing/README.md` → save as `docs/ai/testing/feature-{name}.md`
-
-Ensure the YAML frontmatter and section headings remain identical to the templates before filling in feature-specific content.
-
-## Step 3: Requirements Phase
-Help me fill out `docs/ai/requirements/feature-{name}.md`:
-- Clarify the problem statement
-- Define goals and non-goals
-- Write detailed user stories
-- Establish success criteria
-- Identify constraints and assumptions
-- List open questions
-
-## Step 4: Design Phase
-Guide me through `docs/ai/design/feature-{name}.md`:
-- Propose system architecture changes needed
-- Define data models/schema changes
-- Design API endpoints or interfaces
-- Identify components to create/modify
-- Document key design decisions
-- Note security and performance considerations
-
-## Step 5: Planning Phase
-Help me break down work in `docs/ai/planning/feature-{name}.md`:
-- Create task breakdown with subtasks
-- Identify dependencies (on other features, APIs, etc.)
-- Estimate effort for each task
-- Suggest implementation order
-- Identify risks and mitigation strategies
-
-## Step 6: Documentation Review (Chained Commands)
-Once the docs above are drafted, run the following commands to tighten them up:
-- `/review-requirements` to validate the requirements doc for completeness and clarity
-- `/review-design` to ensure the design doc aligns with requirements and highlights key decisions
-
-(If you are using Claude Code, reference the `review-requirements` and `review-design` commands instead.)
-
-## Step 7: Implementation Phase (Deferred)
-This command focuses on documentation only. Actual implementation happens later via `/execute-plan`.
-For each task in the plan:
-1. Review the task requirements and design
-2. Ask me to confirm I'm starting this task
-3. Guide implementation with reference to design docs
-4. Suggest code structure and patterns
-5. Help with error handling and edge cases
-6. Update `docs/ai/implementation/feature-{name}.md` with notes
-
-## Step 8: Testing Phase
-Guide testing in `docs/ai/testing/feature-{name}.md`:
-- Draft unit test cases with `/writing-test`
-- Draft integration test scenarios with `/writing-test`
-- Recommend manual testing steps
-- Help write test code
-- Verify all success criteria are testable
-
-## Step 9: Local Testing & Verification
-Guide me through:
-1. Running all tests locally
-2. Manual testing checklist
-3. Reviewing against requirements
-4. Checking design compliance
-5. Preparing for code review (diff summary, list of files, design references)
-
-## Step 10: Local Code Review (Optional but recommended)
-Before pushing, ask me to run `/code-review` with the modified file list and relevant docs.
-
-## Step 11: Implementation Execution Reminder
-When ready to implement, run `/execute-plan` to work through the planning doc tasks interactively. That command will orchestrate implementation, testing, and follow-up documentation.
-
-## Step 12: Create Merge/Pull Request
-Provide the MR/PR description:
-```markdown
-## Feature: [Feature Name]
-
-### Summary
-[Brief description of what this feature does]
-
-### Requirements
-- Documented in: `docs/ai/requirements/feature-{name}.md`
-- Related to: [issue/ticket number if applicable]
-
-### Changes
-- [List key changes]
-- [List new files/components]
-- [List modified files]
-
-### Design
-- Architecture: [Link to design doc section]
-- Key decisions: [Brief summary]
-
-### Testing
-- Unit tests: [coverage/status]
-- Integration tests: [status]
-- Manual testing: Completed
-- Test documentation: `docs/ai/testing/feature-{name}.md`
-
-### Checklist
-- [ ] Code follows project standards
-- [ ] All tests pass
-- [ ] Documentation updated
-- [ ] No breaking changes (or documented if any)
-- [ ] Ready for review
-```
-
-Then provide the appropriate command:
-- **GitHub**: `gh pr create --title "feat: [feature-name]" --body-file pr-description.md`
-- **GitLab**: `glab mr create --title "feat: [feature-name]" --description "$(cat mr-description.md)"`
-
----
-
-**Let's start! Tell me about the feature you want to build.**
-
+Guide me through adding a new feature, from requirements documentation to implementation readiness.
+
+1. **Capture Requirement** — If not already provided, ask for: feature name (kebab-case, e.g., `user-authentication`), what problem it solves and who will use it, and key user stories.
+2. **Create Feature Documentation Structure** — Copy each template's content (preserving YAML frontmatter and section headings) into feature-specific files:
+   - `docs/ai/requirements/README.md` → `docs/ai/requirements/feature-{name}.md`
+   - `docs/ai/design/README.md` → `docs/ai/design/feature-{name}.md`
+   - `docs/ai/planning/README.md` → `docs/ai/planning/feature-{name}.md`
+   - `docs/ai/implementation/README.md` → `docs/ai/implementation/feature-{name}.md`
+   - `docs/ai/testing/README.md` → `docs/ai/testing/feature-{name}.md`
+3. **Requirements Phase** — Fill out `docs/ai/requirements/feature-{name}.md`: problem statement, goals/non-goals, user stories, success criteria, constraints, open questions.
+4. **Design Phase** — Fill out `docs/ai/design/feature-{name}.md`: architecture changes, data models, API/interfaces, components, design decisions, security and performance considerations.
+5. **Planning Phase** — Fill out `docs/ai/planning/feature-{name}.md`: task breakdown with subtasks, dependencies, effort estimates, implementation order, risks.
+6. **Documentation Review** — Run `/review-requirements` and `/review-design` to validate the drafted docs.
+7. **Next Steps** — This command focuses on documentation. When ready to implement, use `/execute-plan`. Generate a PR description covering: summary, requirements doc link, key changes, test status, and a readiness checklist.

package/dist/templates/templates/commands/remember.md

@@ -2,26 +2,9 @@
 description: Store reusable guidance in the knowledge memory service.
 ---
 
-# Remember Knowledge
-
 When I say "remember this" or want to save a reusable rule, help me store it in the knowledge memory service.
 
-## Step 1: Capture Knowledge
-Ask me for:
-- A short, explicit title (5-12 words)
-- The detailed content (markdown, examples encouraged)
-- Optional tags (keywords like "api", "testing")
-- Optional scope (`global`, `project:<name>`, `repo:<name>`)
-
-If I'm vague, ask follow-ups to make it specific and actionable.
-
-## Step 2: Validate Quality
-- Ensure it is specific and reusable (not generic advice).
-- Avoid storing secrets or sensitive data.
-
-## Step 3: Store
-Call `memory.storeKnowledge` with title, content, tags, scope.
-If MCP tools are unavailable, use `npx ai-devkit memory store` instead.
-
-## Step 4: Confirm
-Summarize what was saved and offer to store more knowledge if needed.
+1. **Capture Knowledge** — If not already provided, ask for: a short explicit title (5-12 words), detailed content (markdown, examples encouraged), optional tags (keywords like "api", "testing"), and optional scope (`global`, `project:<name>`, `repo:<name>`). If vague, ask follow-ups to make it specific and actionable.
+2. **Validate Quality** — Ensure it is specific and reusable (not generic advice). Avoid storing secrets or sensitive data.
+3. **Store** — Call `memory.storeKnowledge` with title, content, tags, scope. If MCP tools are unavailable, use `npx ai-devkit@latest memory store` instead.
+4. **Confirm** — Summarize what was saved and offer to store more knowledge if needed.

package/dist/templates/templates/commands/review-design.md

@@ -1,5 +1,5 @@
 ---
-description: Review the design documentation for a feature to ensure completeness and accuracy.
+description: Review feature design for completeness.
 ---
 
 Review the design documentation in docs/ai/design/feature-{name}.md (and the project-level README if relevant). Summarize:
@@ -13,4 +13,3 @@ Review the design documentation in docs/ai/design/feature-{name}.md (and the pro
 - Non-functional requirements that must be preserved
 
 Highlight any inconsistencies, missing sections, or diagrams that need updates.
-

package/dist/templates/templates/commands/review-requirements.md

@@ -1,8 +1,8 @@
 ---
-description: Review the requirements documentation for a feature to ensure completeness and alignment with project standards.
+description: Review feature requirements for completeness.
 ---
 
-Please review `docs/ai/requirements/feature-{name}.md` and the project-level template `docs/ai/requirements/README.md` to ensure structure and content alignment. Summarize:
+Review `docs/ai/requirements/feature-{name}.md` and the project-level template `docs/ai/requirements/README.md` to ensure structure and content alignment. Summarize:
 
 - Core problem statement and affected users
 - Goals, non-goals, and success criteria
@@ -11,4 +11,3 @@ Please review `docs/ai/requirements/feature-{name}.md` and the project-level tem
 - Any missing sections or deviations from the template
 
 Identify gaps or contradictions and suggest clarifications.
-

package/dist/templates/templates/commands/simplify-implementation.md

@@ -1,148 +1,10 @@
 ---
-description: Analyze and simplify existing implementations to reduce complexity, improve maintainability, and enhance scalability.
+description: Simplify existing code to reduce complexity.
 ---
 
-# Simplify Implementation Assistant
+Help me simplify an existing implementation while maintaining or improving its functionality.
 
-You are an expert engineer focused on reducing complexity and improving scalability. Help me simplify an existing implementation while maintaining or improving its functionality.
-
-## Step 1: Gather Context
-Ask me for:
-- Target file(s) or component(s) to simplify
-- Current pain points (hard to understand, maintain, or extend?)
-- Performance or scalability concerns
-- Any constraints (backward compatibility, API stability, deadlines)
-- Relevant design docs or requirements
-
-If available, request the current implementation:
-```bash
-# For a specific file
-cat <file_path>
-
-# For recent changes
-git diff HEAD~5 --stat
-```
-
-## Step 2: Analyze Current Complexity
-For each target file or component:
-1. **Identify complexity sources:**
-   - Deep nesting or long functions
-   - Duplicate or redundant code
-   - Unclear abstractions or leaky interfaces
-   - Tightly coupled components
-   - Over-engineering or premature optimization
-   - Magic numbers, hardcoded values, or scattered configuration
-
-2. **Measure impact:**
-   - Lines of code that could be reduced
-   - Number of dependencies that could be removed
-   - Cognitive load for future maintainers
-
-3. **Assess scalability blockers:**
-   - Single points of failure
-   - Synchronous operations that should be async
-   - Missing caching or memoization opportunities
-   - Inefficient data structures or algorithms
-
-## Step 3: Apply Readability Principles
-
-**Core Philosophy: Good code reads like a good book — naturally, from left to right, top to bottom.**
-
-When simplifying, prioritize readability over brevity. The goal is not to write the shortest code, but to write code that communicates intent clearly.
-
-### ✅ DO: Embrace Readability
-- **Linear flow:** Code should tell a story. A reader should understand the logic by reading top-to-bottom without jumping around.
-- **Explicit over implicit:** Favor clear, explicit code over clever shortcuts that require mental decoding.
-- **Meaningful names:** Variables, functions, and classes should describe their purpose without needing comments.
-- **Consistent patterns:** Use the same patterns throughout the codebase so readers build familiarity.
-- **Appropriate abstraction level:** Each function should operate at one level of abstraction.
-- **White space and grouping:** Use blank lines to separate logical blocks, like paragraphs in prose.
-
-### ❌ AVOID: Over-Optimization for Brevity
-Reducing line count is NOT the goal. These patterns often harm readability:
-
-| Anti-Pattern | Problem | Better Alternative |
-|--------------|---------|--------------------|
-| **Nested ternaries** | `a ? b ? c : d : e` is cryptic | Use explicit if/else blocks |
-| **Chained one-liners** | `x.map().filter().reduce().flat()` is hard to debug | Break into named intermediate steps |
-| **Clever bitwise tricks** | `n & 1` instead of `n % 2 === 1` obscures intent | Use readable arithmetic unless performance-critical |
-| **Overly short variable names** | `const x = getData(); const y = x.filter(z => z.a);` | Use descriptive names like `users`, `activeUsers` |
-| **Implicit returns everywhere** | Arrow functions without braces hide complexity | Add braces and explicit returns for complex logic |
-| **Magic one-liners** | Regex or reduce expressions that "do everything" | Split into documented steps |
-| **Premature DRY** | Forcing abstraction to avoid 2-3 lines of duplication | Some duplication is clearer than wrong abstraction |
-
-### 📖 The "Reading Test"
-For each simplification, ask:
-1. Can a new team member understand this in under 30 seconds?
-2. Does the code flow naturally without needing to jump to other files?
-3. Are there any "wait, what does this do?" moments?
-4. Would this code still be clear 6 months from now?
-
-If the answer is "no" to any of these, the code needs more clarity, not more optimization.
-
-## Step 4: Propose Simplifications
-For each identified issue, suggest concrete improvements:
-
-| Category | Pattern |
-|----------|---------|
-| **Extract** | Long functions → smaller, focused functions |
-| **Consolidate** | Duplicate code → shared utilities or base classes |
-| **Flatten** | Deep nesting → early returns, guard clauses |
-| **Decouple** | Tight coupling → dependency injection, interfaces |
-| **Remove** | Dead code, unused features, excessive abstractions |
-| **Replace** | Complex logic → built-in language/library features |
-| **Defer** | Premature optimization → measure-first approach |
-
-## Step 5: Prioritize Changes
-Rank suggestions by:
-1. **High impact, low risk** — Do first
-2. **High impact, higher risk** — Plan carefully
-3. **Low impact, low risk** — Quick wins if time permits
-4. **Low impact, high risk** — Skip or defer
-
-For each change, specify:
-- Before/after code snippets
-- Risk level (breaking change? needs migration?)
-- Testing requirements
-- Estimated effort
-
-## Step 6: Create Simplification Plan
-Provide a structured action plan:
-
-```
-### Simplification Summary
-- Total suggestions: [count]
-- Estimated LOC reduction: [estimate]
-- Complexity score before/after: [if measurable]
-
-### Prioritized Actions
-1. **[Component/Function Name]**
-   - Issue: ...
-   - Solution: ...
-   - Risk: Low/Medium/High
-   - Effort: S/M/L
-
-2. ... (repeat)
-
-### Recommended Order
-1. [ ] [First change - safest, unlocks others]
-2. [ ] [Second change]
-3. [ ] ...
-
-### Post-Simplification Checklist
-- [ ] Run existing tests to verify no regressions
-- [ ] Add tests for any new helper functions
-- [ ] Update documentation if interfaces changed
-- [ ] Review with team before merging larger refactors
-```
-
-## Step 7: Scalability Recommendations
-Beyond immediate simplification, suggest patterns for future scalability:
-- Modular architecture improvements
-- Caching strategies
-- Async/parallel processing opportunities
-- Configuration externalization
-- Feature flags for gradual rollouts
-
----
-Let me know when you're ready to simplify your implementation.
+1. **Gather Context** — If not already provided, ask for: target file(s) or component(s) to simplify, current pain points (hard to understand, maintain, or extend?), performance or scalability concerns, constraints (backward compatibility, API stability, deadlines), and relevant design docs or requirements.
+2. **Analyze Current Complexity** — For each target: identify complexity sources (deep nesting, duplication, unclear abstractions, tight coupling, over-engineering, magic values), assess cognitive load for future maintainers, and identify scalability blockers (single points of failure, sync-where-async-needed, missing caching, inefficient algorithms).
+3. **Propose Simplifications** — Prioritize readability over brevity — apply the 30-second test: can a new team member understand each change quickly? For each issue, suggest concrete improvements (extract, consolidate, flatten, decouple, remove dead code, replace with built-ins). Provide before/after snippets.
+4. **Prioritize & Plan** — Rank by impact vs risk: (1) high impact, low risk — do first, (2) high impact, higher risk — plan carefully, (3) low impact, low risk — quick wins if time permits, (4) low impact, high risk — skip or defer. For each change specify risk level, testing requirements, and effort. Produce a prioritized action plan with recommended execution order.