@minhduydev/mdpi 0.3.0

package/dist/template/.pi/skills/code-review-and-quality/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: code-review-and-quality
+description: Reviews code for correctness, regressions, security, maintainability, and goal completion. Use before merge, after subagent work, or when asked for a review.
+---
+
+# Code Review & Quality
+
+## Overview
+
+Review is a bug-finding activity, not a compliment sandwich. Verify the goal is achieved and no unacceptable risk is introduced.
+
+Core principle: findings first, with `file:line` evidence and impact.
+
+**Complexity is a correctness issue.** Working code that adds structural complexity makes future changes harder, slower, and more error-prone. Reviewers must weigh structural quality alongside behavior.
+
+Use the **three complexity symptoms** (Ousterhout) as review lenses:
+- **Change amplification**: a small future change requires touching many places.
+- **Cognitive load**: the reviewer must understand too much of the system to assess one change.
+- **Unknown unknowns**: hidden dependencies hide what must change for a new requirement.
+
+Approve when the change clearly improves overall code health, even if imperfect. Do not block solely because you would have written it differently.
+
+## When to Use
+
+- User asks for review.
+- Before merge/ship or after a worker/subagent reports completion.
+- Refactors, security-sensitive changes, API changes, migrations, concurrency, or auth.
+- Any change where complexity may have been introduced (always suspect).
+
+## When NOT to Use
+
+- Planning decisions before code exists; use `planning-and-task-breakdown`.
+- Implementation; reviewer must stay read-only.
+- Style-only commentary unless it hides a real bug.
+
+## The Five-Axis Review
+
+Evaluate every change across:
+
+### 1. Correctness
+- Matches the spec or task requirements.
+- Edge cases handled (null, empty, boundary values).
+- Error paths handled, not only happy path.
+- Tests pass and test the right things; no off-by-one or race conditions.
+
+### 2. Readability & Simplicity
+- Names are descriptive and consistent (no `temp`, `data`, `result` without context).
+- Control flow is straightforward; related code is grouped.
+- No "clever" tricks; abstractions earn their complexity.
+- Comments clarify non-obvious intent, not obvious code.
+
+### 3. Architecture
+- Follows existing patterns or justifies a new one.
+- Clean module boundaries; dependencies flow the right way.
+- Duplication extracted when appropriate; abstraction level is right.
+
+### 4. Security
+Load `security-and-hardening` for detailed guidance. Check input validation at boundaries, secrets out of code/logs, auth/authz, parameterized queries, XSS encoding, trusted dependencies, and untrusted external data.
+
+### 5. Performance
+Load `performance-optimization` for detailed guidance. Check N+1 queries, unbounded loops, sync-in-async, unnecessary re-renders, missing pagination, and hot-path allocations.
+
+## Review Process
+
+### Step 1: Understand the Context
+- What is this change trying to accomplish?
+- What spec or task does it implement?
+- What is the expected behavior change?
+
+### Step 2: Review the Tests First
+- Do tests exist and test behavior (not implementation details)?
+- Are edge cases covered?
+- Do tests have descriptive names?
+- Would they catch a regression if the code changed?
+
+### Step 3: Review the Implementation
+Walk through changed files with the five axes in mind: correctness, readability, architecture, security, performance.
+
+### Step 4: Categorize Findings
+Label every comment so the author knows what is required versus optional.
+
+| Prefix | Meaning | Author Action |
+| --- | --- | --- |
+| *(no prefix)* | Required change | Must address before merge |
+| **Critical:** | Blocks merge | Security vulnerability, data loss, broken functionality |
+| **Nit:** | Minor, optional | Author may ignore — formatting, style preferences |
+| **Optional:** / **Consider:** | Suggestion | Worth considering but not required |
+| **FYI** | Informational only | No action needed — context for future reference |
+
+### Step 5: Verify the Verification
+- What tests were run?
+- Did the build pass?
+- Was the change tested manually?
+- Are there screenshots for UI changes?
+- Is there a before/after comparison?
+
+## Change Sizing
+
+Small, focused changes are easier to review, faster to merge, and safer to deploy.
+
+| Size | Verdict |
+| --- | --- |
+| ~100 lines changed | Good. Reviewable in one sitting. |
+| ~300 lines changed | Acceptable if it is a single logical change. |
+| ~1000 lines changed | Too large. Split it. |
+
+**What counts as "one change":** a single self-contained modification that addresses one thing, includes related tests, and keeps the system functional after submission.
+
+**Splitting strategies:**
+
+| Strategy | How | When |
+| --- | --- | --- |
+| **Stack** | Submit a small change, then start the next one based on it | Sequential dependencies |
+| **By file group** | Separate changes for groups needing different reviewers | Cross-cutting concerns |
+| **Horizontal** | Create shared code/stubs first, then consumers | Layered architecture |
+| **Vertical** | Break into smaller full-stack slices of the feature | Feature work |
+
+**When large changes are acceptable:** complete file deletions and automated refactoring where the reviewer only verifies intent, not every line.
+
+**Separate refactoring from feature work.** A change that refactors existing code and adds new behavior is two changes. Small cleanups can be included at reviewer discretion.
+
+## Severity
+
+Internal priority scale:
+
+| Priority | Meaning |
+| --- | --- |
+| P0 | Critical: data loss, security break, crash on common path, release blocker. |
+| P1 | High: likely user-visible bug or serious regression. |
+| P2 | Medium: edge-case bug, maintainability hazard with concrete impact. |
+| P3 | Low: minor issue worth fixing but not blocking. |
+
+Map review labels to priorities:
+- **Critical:** → P0/P1
+- *(no prefix)* → P1/P2
+- **Optional:** / **Consider:** → P2/P3
+- **Nit:** / **FYI** → P3 or informational
+
+## Finding Template
+
+```text
+[P1] Title — path/to/file.ts:42
+Impact: What breaks and when.
+Evidence: Concrete code behavior.
+Confidence: 0.0-1.0
+```
+
+## Broken Windows Scan
+
+A change should not normalize decay. Scan changed files for:
+- Messy or unused imports, inconsistent formatting.
+- Inconsistent naming or patterns within the same file.
+- TODO comments without ticket references.
+- Dead code, no-op handlers, static placeholder responses.
+- Created files that are not imported or invoked anywhere.
+- README/AGENTS.md drift caused by the change.
+
+Fix broken windows in changed files; flag adjacent decay without widening scope unnecessarily.
+
+## Dead Code Hygiene
+
+After any refactoring or implementation change, check for orphaned code:
+1. Identify code that is now unreachable or unused.
+2. List it explicitly.
+3. **Ask before deleting:** "Should I remove these now-unused elements: [list]?"
+
+Do not leave dead code lying around, but do not silently delete things you are not sure about.
+
+```text
+DEAD CODE IDENTIFIED:
+- formatLegacyDate() in src/utils/date.ts — replaced by formatDate()
+- OldTaskCard in src/components/ — replaced by TaskCard
+- LEGACY_API_URL in src/config.ts — no remaining references
+→ Safe to remove these?
+```
+
+## Multi-Model Review Pattern
+
+Use different models or agent runs for different review perspectives:
+
+```text
+Model A writes the code
+    │
+    ▼
+Model B reviews for correctness and architecture
+    │
+    ▼
+Model A addresses the feedback
+    │
+    ▼
+Human or lead agent makes the final call
+```
+
+This catches issues a single model might miss. Example prompt:
+
+```text
+Review this code change for correctness, security, and adherence to
+project conventions. The spec says [X]. The change should [Y].
+Flag any issues as Critical, Important, or Suggestion.
+```
+
+## Review Speed
+
+Slow reviews block teams. The cost of context-switching to review is less than the waiting cost imposed on others.
+- **Respond within one business day** — maximum, not target.
+- **Ideal cadence:** respond shortly after a review request arrives, unless deep in focused coding. A typical change should complete multiple review rounds in a single day.
+- **Prioritize fast individual responses** over quick final approval. Quick feedback reduces frustration even if multiple rounds are needed.
+- **Large changes:** ask the author to split them rather than reviewing one massive changeset.
+
+## Handling Disagreements
+
+When resolving review disputes, apply this hierarchy:
+1. **Technical facts and data** override opinions and preferences.
+2. **Style guides** are the absolute authority on style matters.
+3. **Software design** must be evaluated on engineering principles, not personal preference.
+4. **Codebase consistency** is acceptable if it does not degrade overall health.
+
+Do not accept "I'll clean it up later." Experience shows deferred cleanup rarely happens. Require cleanup before submission unless it is a genuine emergency. If surrounding issues cannot be addressed in this change, require filing a follow-up with self-assignment.
+
+## Honesty in Review
+
+When reviewing code — whether written by you, another agent, or a human:
+- **Do not rubber-stamp.** "LGTM" without evidence of review helps no one.
+- **Do not soften real issues.** "This might be a minor concern" when it is a production bug is dishonest.
+- **Quantify problems when possible.** "This N+1 query will add ~50ms per item" is better than "this could be slow."
+- **Push back on approaches with clear problems.** Sycophancy is a failure mode in reviews. If the implementation has issues, say so directly and propose alternatives.
+- **Accept override gracefully.** If the author has full context and disagrees, defer to their judgment. Comment on code, not people — reframe personal critiques to focus on the code itself.
+
+## Dependency Discipline
+
+Part of code review is dependency review.
+
+**Before adding any dependency:**
+1. Does the existing stack solve this? (Often it does.)
+2. How large is the dependency? (Check bundle impact.)
+3. Is it actively maintained? (Check last commit, open issues.)
+4. Does it have known vulnerabilities? (`npm audit` or equivalent.)
+5. What is the license? (Must be compatible with the project.)
+
+**Rule:** prefer standard library and existing utilities over new dependencies. Every dependency is a liability.
+
+## Full Review Checklist
+
+```markdown
+## Review: [PR/Change title]
+
+### Context
+- [ ] I understand what this change does and why
+
+### Correctness
+- [ ] Matches spec; edge cases and error paths handled; tests adequate
+
+### Readability
+- [ ] Names clear and consistent; logic straightforward; no unnecessary complexity
+
+### Architecture
+- [ ] Follows existing patterns; no unnecessary coupling; abstraction level appropriate
+
+### Security
+- [ ] No secrets; input validated; no injection; auth checks; external data untrusted
+
+### Performance
+- [ ] No N+1 or unbounded ops; pagination on list endpoints
+
+### Verification
+- [ ] Tests pass; build succeeds; manual verification done if applicable
+
+### Verdict
+- [ ] **Approve** — Ready to merge
+- [ ] **Request changes** — Issues must be addressed
+```
+
+## Common Rationalizations
+
+| Rationalization | Rebuttal |
+| --- | --- |
+| "The implementation looks reasonable" | Review behavior and wiring, not aesthetics. |
+| "The worker said tests pass" | Verify independently or mark as unverified. |
+| "This is probably pre-existing" | Only skip if evidence shows it was not introduced or worsened. |
+| "I should mention style too" | Style-only noise hides real findings. |
+| "It works, that's good enough" | Working code that is unreadable, insecure, or architecturally wrong creates compounding debt. |
+| "I wrote it, so I know it's correct" | Authors are blind to their own assumptions. Every change benefits from another set of eyes. |
+| "We'll clean it up later" | Later never comes. Require cleanup before merge. |
+| "AI-generated code is probably fine" | AI code needs more scrutiny, not less. |
+| "The tests pass, so it's good" | Tests are necessary but not sufficient. They do not catch architecture, security, or readability problems. |
+
+## Red Flags
+
+- No `file:line` evidence for a finding.
+- Findings describe preferences rather than bugs/risks.
+- Review ignores acceptance criteria.
+- Created files are not imported or invoked anywhere.
+- Static placeholder responses or no-op handlers satisfy superficial tests.
+- Reviewer modifies files.
+- PRs merged without any review.
+- Review that only checks if tests pass (ignoring other axes).
+- "LGTM" without evidence of actual review.
+- Security-sensitive changes without security-focused review.
+- Large PRs that are "too big to review properly" (split them).
+- No regression tests with bug fix PRs.
+- Review comments without severity labels.
+- Accepting "I'll fix it later" — it rarely happens.
+
+## Complexity Red Flags
+
+- **New module with shallow interface**: lots of public methods/props for small implementation — it is not hiding complexity, it is exposing it.
+- **Information leakage**: one module exposes internal implementation details another module depends on.
+- **Change amplification signal**: a simple conceptual change would touch many files — the structure is fighting the domain.
+- **Cognitive load spike**: the diff requires understanding 5+ unrelated files to verify one change.
+- **Pass-through methods**: methods that do nothing but delegate with the same signature — a sign the abstraction boundary is wrong.
+- **Broken windows introduced**: messy formatting, dead imports, TODOs without tickets, inconsistent conventions within the same file.
+
+## Verification
+
+After review is complete:
+- [ ] All Critical/P0 issues are resolved.
+- [ ] P1/P2 issues are resolved or explicitly deferred with justification.
+- [ ] Tests pass and build succeeds.
+- [ ] The verification story is documented.
+- [ ] Changed artifacts exist, are substantive, and key links are wired.
+- [ ] Findings are ordered by severity; verdict is explicit: correct or incorrect.
+
+## Skill Result Contract
+
+```xml
+<skill_result>
+  <skill>code-review-and-quality</skill>
+  <status>success|partial|blocked|failure</status>
+  <evidence>Files reviewed, commands/checks run, findings with file:line evidence</evidence>
+  <artifacts>Reviewed files or diff range</artifacts>
+  <risks>Untested areas, unavailable base, or none</risks>
+</skill_result>
+```
+
+## Consolidated Review Workflow
+
+This is the canonical active review skill. It absorbs requesting-code-review, receiving-code-review, sprint-review, and reconcile responsibilities.
+
+Use it for:
+- self-review before claiming completion;
+- subagent or peer review routing;
+- skeptical treatment of received review comments;
+- severity-ranked findings with file/line evidence;
+- reconciliation between user intent, implementation, tests, and remaining risk.

package/dist/template/.pi/skills/code-simplification/SKILL.md

@@ -0,0 +1,348 @@
+---
+name: code-simplification
+description: "Simplifies code for clarity without changing behavior. Auto-load when editing *.ts,*.tsx,*.py,*.js with complexity issues. Use when: code works but is hard to read/maintain/extend, refactoring for clarity, reviewing accumulated complexity, or user says 'simplify this' / 'too complex' / 'clean up'. Risk: Low (reads code, proposes changes, does NOT execute without user review)."
+---
+
+# Code Simplification
+
+> Inspired by the [Claude Code Simplifier plugin](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/code-simplifier/agents/code-simplifier.md). Adapted here as a model-agnostic, process-driven skill for any AI coding agent.
+
+## Overview
+
+Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"
+
+> **Risk Level: Low** — This skill reads and proposes changes but should NOT auto-execute. All simplifications must be reviewed before committing. Use `/skill:code-simplification` explicitly or load alongside `code-review-and-quality` for gated review.
+
+## When to Use
+
+- After a feature is working and tests pass, but the implementation feels heavier than it needs to be
+- During code review when readability or complexity issues are flagged
+- When you encounter deeply nested logic, long functions, or unclear names
+- When refactoring code written under time pressure
+- When consolidating related logic scattered across files
+- After merging changes that introduced duplication or inconsistency
+
+## When NOT to Use
+
+- Code is already clean and readable — don't simplify for the sake of it
+- You don't understand what the code does yet — comprehend before you simplify
+- The code is performance-critical and the "simpler" version would be measurably slower
+- You're about to rewrite the module entirely — simplifying throwaway code wastes effort
+
+## The Five Principles
+
+### 1. Preserve Behavior Exactly
+
+Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.
+
+```
+ASK BEFORE EVERY CHANGE:
+→ Does this produce the same output for every input?
+→ Does this maintain the same error behavior?
+→ Does this preserve the same side effects and ordering?
+→ Do all existing tests still pass without modification?
+```
+
+### 2. Follow Project Conventions
+
+Simplification means making code more consistent with the codebase, not imposing external preferences. Before simplifying:
+
+```
+1. Read project conventions (AGENTS.md, CLAUDE.md, etc.)
+2. Study how neighboring code handles similar patterns
+3. Match the project's style for:
+   - Import ordering and module system
+   - Function declaration style
+   - Naming conventions
+   - Error handling patterns
+   - Type annotation depth
+```
+
+Simplification that breaks project consistency is not simplification — it's churn.
+
+### 3. Prefer Clarity Over Cleverness
+
+Explicit code is better than compact code when the compact version requires a mental pause to parse.
+
+```typescript
+// UNCLEAR: Dense ternary chain
+const label = isNew ? 'New' : isUpdated ? 'Updated' : isArchived ? 'Archived' : 'Active';
+
+// CLEAR: Readable mapping
+function getStatusLabel(item: Item): string {
+  if (item.isNew) return 'New';
+  if (item.isUpdated) return 'Updated';
+  if (item.isArchived) return 'Archived';
+  return 'Active';
+}
+```
+
+```typescript
+// UNCLEAR: Chained reduces with inline logic
+const result = items.reduce((acc, item) => ({
+  ...acc,
+  [item.id]: { ...acc[item.id], count: (acc[item.id]?.count ?? 0) + 1 }
+}), {});
+
+// CLEAR: Named intermediate step
+const countById = new Map<string, number>();
+for (const item of items) {
+  countById.set(item.id, (countById.get(item.id) ?? 0) + 1);
+}
+```
+
+### 4. Maintain Balance
+
+Simplification has a failure mode: over-simplification. Watch for these traps:
+
+- **Inlining too aggressively** — removing a helper that gave a concept a name makes the call site harder to read
+- **Combining unrelated logic** — two simple functions merged into one complex function is not simpler
+- **Removing "unnecessary" abstraction** — some abstractions exist for extensibility or testability, not complexity
+- **Optimizing for line count** — fewer lines is not the goal; easier comprehension is
+
+### 5. Scope to What Changed
+
+Default to simplifying recently modified code. Avoid drive-by refactors of unrelated code unless explicitly asked to broaden scope. Unscoped simplification creates noise in diffs and risks unintended regressions.
+
+## The Simplification Process
+
+### Step 1: Understand Before Touching (Chesterton's Fence)
+
+Before changing or removing anything, understand why it exists. This is Chesterton's Fence: if you see a fence across a road and don't understand why it's there, don't tear it down. First understand the reason, then decide if the reason still applies.
+
+```
+BEFORE SIMPLIFYING, ANSWER:
+- What is this code's responsibility?
+- What calls it? What does it call?
+- What are the edge cases and error paths?
+- Are there tests that define the expected behavior?
+- Why might it have been written this way? (Performance? Platform constraint? Historical reason?)
+- Check git blame: what was the original context for this code?
+```
+
+If you can't answer these, you're not ready to simplify. Read more context first.
+
+### Step 2: Identify Simplification Opportunities
+
+Scan for these patterns — each one is a concrete signal, not a vague smell:
+
+**Structural complexity:**
+
+| Pattern | Signal | Simplification |
+|---------|--------|----------------|
+| Deep nesting (3+ levels) | Hard to follow control flow | Extract conditions into guard clauses or helper functions |
+| Long functions (50+ lines) | Multiple responsibilities | Split into focused functions with descriptive names |
+| Nested ternaries | Requires mental stack to parse | Replace with if/else chains, switch, or lookup objects |
+| Boolean parameter flags | `doThing(true, false, true)` | Replace with options objects or separate functions |
+| Repeated conditionals | Same `if` check in multiple places | Extract to a well-named predicate function |
+
+**Naming and readability:**
+
+| Pattern | Signal | Simplification |
+|---------|--------|----------------|
+| Generic names | `data`, `result`, `temp`, `val`, `item` | Rename to describe the content: `userProfile`, `validationErrors` |
+| Abbreviated names | `usr`, `cfg`, `btn`, `evt` | Use full words unless the abbreviation is universal (`id`, `url`, `api`) |
+| Misleading names | Function named `get` that also mutates state | Rename to reflect actual behavior |
+| Comments explaining "what" | `// increment counter` above `count++` | Delete the comment — the code is clear enough |
+| Comments explaining "why" | `// Retry because the API is flaky under load` | Keep these — they carry intent the code can't express |
+
+**Redundancy:**
+
+| Pattern | Signal | Simplification |
+|---------|--------|----------------|
+| Duplicated logic | Same 5+ lines in multiple places | Extract to a shared function |
+| Dead code | Unreachable branches, unused variables, commented-out blocks | Remove (after confirming it's truly dead) |
+| Unnecessary abstractions | Wrapper that adds no value | Inline the wrapper, call the underlying function directly |
+| Over-engineered patterns | Factory-for-a-factory, strategy-with-one-strategy | Replace with the simple direct approach |
+| Redundant type assertions | Casting to a type that's already inferred | Remove the assertion |
+
+### Step 3: Apply Changes Incrementally
+
+Make one simplification at a time. Run tests after each change. **Submit refactoring changes separately from feature or bug fix changes.** A PR that refactors and adds a feature is two PRs — split them.
+
+```
+FOR EACH SIMPLIFICATION:
+1. Make the change
+2. Run the test suite
+3. If tests pass → commit (or continue to next simplification)
+4. If tests fail → revert and reconsider
+```
+
+Avoid batching multiple simplifications into a single untested change. If something breaks, you need to know which simplification caused it.
+
+**The Rule of 500:** If a refactoring would touch more than 500 lines, invest in automation (codemods, sed scripts, AST transforms) rather than making the changes by hand. Manual edits at that scale are error-prone and exhausting to review.
+
+### Step 4: Verify the Result
+
+After all simplifications, step back and evaluate the whole:
+
+```
+COMPARE BEFORE AND AFTER:
+- Is the simplified version genuinely easier to understand?
+- Did you introduce any new patterns inconsistent with the codebase?
+- Is the diff clean and reviewable?
+- Would a teammate approve this change?
+```
+
+If the "simplified" version is harder to understand or review, revert. Not every simplification attempt succeeds.
+
+## Language-Specific Guidance
+
+### TypeScript / JavaScript
+
+```typescript
+// SIMPLIFY: Unnecessary async wrapper
+// Before
+async function getUser(id: string): Promise<User> {
+  return await userService.findById(id);
+}
+// After
+function getUser(id: string): Promise<User> {
+  return userService.findById(id);
+}
+
+// SIMPLIFY: Verbose conditional assignment
+// Before
+let displayName: string;
+if (user.nickname) {
+  displayName = user.nickname;
+} else {
+  displayName = user.fullName;
+}
+// After
+const displayName = user.nickname || user.fullName;
+
+// SIMPLIFY: Manual array building
+// Before
+const activeUsers: User[] = [];
+for (const user of users) {
+  if (user.isActive) {
+    activeUsers.push(user);
+  }
+}
+// After
+const activeUsers = users.filter((user) => user.isActive);
+
+// SIMPLIFY: Redundant boolean return
+// Before
+function isValid(input: string): boolean {
+  if (input.length > 0 && input.length < 100) {
+    return true;
+  }
+  return false;
+}
+// After
+function isValid(input: string): boolean {
+  return input.length > 0 && input.length < 100;
+}
+```
+
+### Python
+
+```python
+# SIMPLIFY: Verbose dictionary building
+# Before
+result = {}
+for item in items:
+    result[item.id] = item.name
+# After
+result = {item.id: item.name for item in items}
+
+# SIMPLIFY: Nested conditionals with early return
+# Before
+def process(data):
+    if data is not None:
+        if data.is_valid():
+            if data.has_permission():
+                return do_work(data)
+            else:
+                raise PermissionError("No permission")
+        else:
+            raise ValueError("Invalid data")
+    else:
+        raise TypeError("Data is None")
+# After
+def process(data):
+    if data is None:
+        raise TypeError("Data is None")
+    if not data.is_valid():
+        raise ValueError("Invalid data")
+    if not data.has_permission():
+        raise PermissionError("No permission")
+    return do_work(data)
+```
+
+### React / JSX
+
+```tsx
+// SIMPLIFY: Verbose conditional rendering
+// Before
+function UserBadge({ user }: Props) {
+  if (user.isAdmin) {
+    return <Badge variant="admin">Admin</Badge>;
+  } else {
+    return <Badge variant="default">User</Badge>;
+  }
+}
+// After
+function UserBadge({ user }: Props) {
+  const variant = user.isAdmin ? 'admin' : 'default';
+  const label = user.isAdmin ? 'Admin' : 'User';
+  return <Badge variant={variant}>{label}</Badge>;
+}
+
+// SIMPLIFY: Prop drilling through intermediate components
+// Before — consider whether context or composition solves this better.
+// This is a judgment call — flag it, don't auto-refactor.
+```
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "It's working, no need to touch it" | Working code that's hard to read will be hard to fix when it breaks. Simplifying now saves time on every future change. |
+| "Fewer lines is always simpler" | A 1-line nested ternary is not simpler than a 5-line if/else. Simplicity is about comprehension speed, not line count. |
+| "I'll just quickly simplify this unrelated code too" | Unscoped simplification creates noisy diffs and risks regressions in code you didn't intend to change. Stay focused. |
+| "The types make it self-documenting" | Types document structure, not intent. A well-named function explains *why* better than a type signature explains *what*. |
+| "This abstraction might be useful later" | Don't preserve speculative abstractions. If it's not used now, it's complexity without value. Remove it and re-add when needed. |
+| "The original author must have had a reason" | Maybe. Check git blame — apply Chesterton's Fence. But accumulated complexity often has no reason; it's just the residue of iteration under pressure. |
+| "I'll refactor while adding this feature" | Separate refactoring from feature work. Mixed changes are harder to review, revert, and understand in history. |
+
+## Red Flags
+
+- Simplification that requires modifying tests to pass (you likely changed behavior)
+- "Simplified" code that is longer and harder to follow than the original
+- Renaming things to match your preferences rather than project conventions
+- Removing error handling because "it makes the code cleaner"
+- Simplifying code you don't fully understand
+- Batching many simplifications into one large, hard-to-review commit
+- Refactoring code outside the scope of the current task without being asked
+
+## Related Skills
+
+This skill composes with others for a complete quality pipeline. Load these together when appropriate:
+
+| Skill | Relationship | When to combine |
+|-------|-------------|-----------------|
+| `code-cleanup` | Sibling | `code-cleanup` is for noisy/repetitive diffs after behavior works. `code-simplification` is for structural complexity reduction. Use both when code is both messy AND complex. |
+| `code-review-and-quality` | Gate | Run `code-simplification` first, then `code-review-and-quality` to verify simplifications are correct and safe. |
+| `deep-module-design` | Upstream | Apply `deep-module-design` principles BEFORE simplifying — good module boundaries make simplification easier. |
+| `incremental-implementation` | Process | `code-simplification` works best one change at a time. `incremental-implementation` enforces this discipline. |
+| `defense-in-depth` | Complement | When simplifying validation logic or error handling, `defense-in-depth` ensures you don't weaken safety layers. |
+| `behavioral-kernel` | Guardrail | If simplification starts drifting into over-engineering or scope creep, `behavioral-kernel` re-centers. |
+
+**Pipeline**: `deep-module-design` → `code-simplification` → `code-review-and-quality` → `verification-before-completion`
+
+## Verification
+
+After completing a simplification pass:
+
+- [ ] All existing tests pass without modification
+- [ ] Build succeeds with no new warnings
+- [ ] Linter/formatter passes (no style regressions)
+- [ ] Each simplification is a reviewable, incremental change
+- [ ] The diff is clean — no unrelated changes mixed in
+- [ ] Simplified code follows project conventions (checked against AGENTS.md or equivalent)
+- [ ] No error handling was removed or weakened
+- [ ] No dead code was left behind (unused imports, unreachable branches)
+- [ ] A teammate or review agent would approve the change as a net improvement