Skip to content

feat(skills): enhance Simplify skill with 3-reviewer pattern and MAXSIM integration #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
maystudios wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(skills): enhance Simplify skill with 3-reviewer pattern and MAXSIM integration #15

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 75 additions & 3 deletions templates/skills/simplify/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
---
name: simplify
description: Use after implementation and before commit — requires reviewing changed code for reuse opportunities, quality issues, and unnecessary complexity
context: fork
---
Copy link

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The context: fork frontmatter key added on line 4 does not appear in any other skill or command template in this repository. There is no documentation explaining what this key means, what system reads it, or what behavior it enables (e.g., whether it triggers a forked context in Claude, spawns a subagent, or has some other effect). Without this explanation, readers cannot understand the intent or verify the key is correct. Either add an inline comment explaining the purpose of this key, or point to where it is defined/consumed in the system.

Suggested change
---
---
<!-- `context: fork` is consumed by the skill runner/orchestration layer to execute this skill in a forked/isolated assistant context; it is not standard Markdown and is ignored by normal renderers. -->

Copilot uses AI. Check for mistakes.

# Simplify
Expand All @@ -18,6 +19,47 @@ If you have not checked for duplication, dead code, and unnecessary complexity,
Violating this rule is a violation — not a preference.
</HARD-GATE>

## Three-Reviewer Protocol

For significant changes (10+ files or 200+ lines changed), run three parallel review passes. For smaller changes, a single sequential pass through the gate function steps below is sufficient.
Copy link

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is a threshold inconsistency between the section introduction and the "When to Use" table. Line 24 states that the parallel protocol applies to "significant changes (10+ files or 200+ lines changed)" and "smaller changes" get sequential — implying only two tiers. However, the table on lines 57–61 introduces a third middle tier ("5–10 files, 100–200 lines: Sequential with extra attention to duplication") that is never mentioned in the introduction. A reader relying only on the summary paragraph will not know this middle tier exists, leading to skipped or wrong protocol selection. The introduction should be updated to acknowledge all three tiers, or the table should be referenced explicitly in the introduction.

Suggested change
For significant changes (10+ files or 200+ lines changed), run three parallel review passes. For smaller changes, a single sequential pass through the gate function steps below is sufficient.
For significant changes (10+ files or 200+ lines changed), run three parallel review passes. For medium-sized changes (around 5–10 files or 100–200 lines changed), use the sequential gate function but apply extra attention to duplication as outlined in the “When to Use” table below. For smaller changes beneath these thresholds, a single sequential pass through the gate function steps is sufficient.

Copilot uses AI. Check for mistakes.

### Parallel Review Passes

**Reviewer A — Duplication & Dead Code:**
Focus exclusively on steps 2 (DUPLICATION) and 3 (DEAD CODE) of the gate function.
- Scan the entire diff for copy-paste patterns
- Cross-reference new code against the existing codebase for existing utilities
- Flag all unused imports, variables, unreachable branches, commented code

**Reviewer B — Complexity & Abstraction:**
Focus exclusively on step 4 (COMPLEXITY) of the gate function.
- Challenge every new abstraction, wrapper, and indirection layer
- Flag generic solutions where specific ones suffice
- Identify premature configuration and extension points

**Reviewer C — Clarity & Efficiency:**
Focus exclusively on steps 5 (CLARITY) and 6 (EFFICIENCY) of the gate function.
- Review naming for self-evidence
- Flatten nested conditions, simplify control flow
- Flag obvious O(n²) operations and repeated computations

### Aggregation

After all three reviewers complete:
1. Merge findings — deduplicate overlapping issues
2. Resolve conflicts — if reviewers disagree, prefer the simpler option
3. Apply changes — make all simplifications in a single pass
4. Re-run tests — verify nothing broke
5. Re-diff — confirm the simplification actually reduced complexity

### When to Use Sequential vs Parallel

| Change Size | Approach |
|------------|----------|
| < 5 files, < 100 lines | Sequential (single pass through gate function) |
| 5-10 files, 100-200 lines | Sequential with extra attention to duplication |
| 10+ files or 200+ lines | Three-reviewer parallel protocol |

## The Gate Function

After implementation is complete and tests pass, BEFORE committing:
Expand Down Expand Up @@ -128,10 +170,40 @@ Before committing, confirm:
- [ ] No obvious efficiency issues (unnecessary O(n^2), repeated computations)
- [ ] Tests still pass after simplification changes

## In MAXSIM Plan Execution
## Integration with MAXSIM

### Context Loading

Simplification applies at the task level, after implementation and before commit:
When simplifying within a MAXSIM project, load project context:

```bash
node ~/.claude/maxsim/bin/maxsim-tools.cjs skill-context simplify
Copy link

Copilot AI Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The skill-context subcommand used in the bash snippet does not appear to exist in the maxsim-tools.cjs binary anywhere in the codebase. A search across all templates shows every other usage of maxsim-tools.cjs uses subcommands like init, state, roadmap, commit, etc., but skill-context is referenced only in this new section. If this subcommand has not yet been implemented, the command will fail at runtime with an unrecognized command error, giving misleading guidance to users of the skill.

Suggested change
node ~/.claude/maxsim/bin/maxsim-tools.cjs skill-context simplify
node ~/.claude/maxsim/bin/maxsim-tools.cjs state

Copilot uses AI. Check for mistakes.
```

This returns the current phase and codebase conventions. Use this to:
- Reference `.planning/codebase/CONVENTIONS.md` for project naming and style rules
- Reference `.planning/codebase/STRUCTURE.md` for where shared utilities live
- Know which phase's code you are simplifying

### Task-Level Simplification

In MAXSIM plan execution, simplification applies at the task level:
- After task implementation is complete and tests pass, run this review
- Make simplification changes as part of the same commit (not a separate task)
- If simplification reveals a larger refactoring opportunity, file a todo — do not scope-creep
- Track significant simplifications in the task's commit message (e.g., "extracted shared helper for X")
- Track significant simplifications in the task's commit message

### Metrics Tracking

Record simplification metrics for phase documentation:
- Lines removed vs added (net reduction is the goal)
- Helpers extracted (shared utilities created)
- Dead code removed (imports, functions, branches)
- These feed into SUMMARY.md performance section

### STATE.md Hooks

Track significant simplification decisions:
- If a simplification changes a public interface, record as a decision
- If a simplification removes a feature, verify it was unused before recording
- Track cumulative code reduction across the phase