forge-orkes 0.3.8 → 0.3.10

package/template/.claude/skills/refactoring/SKILL.md

@@ -1,168 +0,0 @@
----
-name: refactoring
-description: "Review code built during a milestone for refactoring opportunities. Runs after auditing passes. Produces a structured backlog of improvements the user can work through via quick-tasking. Soft gate — review items, add to backlog, complete milestone."
----
-
-# Refactoring: Post-Milestone Code Review for Improvement Opportunities
-
-You review the code built during a milestone and catalog opportunities for improvement. This is not about correctness (that's `verifying`) or health (that's `auditing`) — it's about identifying code that works but could be cleaner, simpler, or more consistent.
-
-## When to Trigger
-
-- **Automatically** after `auditing` completes (all three paths: HEALTHY, NEEDS ATTENTION after fix, ACCEPTABLE WITH CAVEATS after accept)
-- **On-demand** at any time via user request
-
-## Step 1: Read Context
-
-```
-Read: .forge/project.yml → tech stack, conventions
-Read: .forge/state/milestone-{id}.yml → milestone ID, name, phases completed
-Read: .forge/audits/milestone-{id}-health-report.md → health findings (avoid overlap)
-Read: .forge/refactor-backlog.yml → existing backlog items (if any)
-Read: .forge/constitution.md → active architectural gates (if exists)
-```
-
-Determine the milestone's starting point for the git diff:
-- Check git log for the commit tagged or noted as the milestone start
-- If unavailable, use the first commit after the previous milestone's completion date
-- Fallback: ask the user for the starting commit or branch
-
-## Step 2: Scan Milestone Code
-
-Spawn a fresh agent with isolated context. Pass it:
-- The explicit list of files changed during the milestone (from `git diff --name-only {start}..HEAD`)
-- The tech stack from `project.yml`
-- The health report findings (so it doesn't duplicate auditing's work)
-- The constitution (so it respects intentional decisions)
-
-**The agent scans for 6 categories:**
-
-| # | Category | What to Look For |
-|---|----------|-----------------|
-| 1 | **Duplication** | Similar logic in 2+ places that could be extracted into a shared function, hook, or utility |
-| 2 | **Complexity hotspots** | Functions >50 lines, nesting >3 levels deep, high cyclomatic complexity, overly long files |
-| 3 | **Naming & clarity** | Unclear variable/function names, misleading abstractions, functions that do more than their name suggests |
-| 4 | **Pattern inconsistency** | Same thing done differently across the milestone's files (e.g., error handling, data fetching, state management) |
-| 5 | **Dead code** | Unused functions, unreachable branches, commented-out code left behind, unused imports |
-| 6 | **Abstraction issues** | Over-engineered helpers used once, repeated inline code that warrants extraction, premature or missing abstractions |
-
-**Agent behavior rules:**
-- Read every file in the diff. No sampling.
-- Every finding must reference a specific file and line range.
-- Understand context — don't flag intentional patterns documented in the constitution.
-- Don't duplicate findings already in the health report from auditing.
-- Estimate effort for each item: `quick` (< 30 min, under 50 lines) or `standard` (needs planning).
-- Suggest a concrete approach for each finding, not just "refactor this."
-- Prefer fewer high-quality findings over many low-signal ones.
-
-**Output format** (return to orchestrator):
-
-```yaml
-findings:
-  - category: duplication
-    file: "src/api/users.ts"
-    lines: "42-67"
-    description: "Duplicate validation logic — same email check in createUser and updateUser"
-    effort: quick
-    suggested_approach: "Extract shared validateEmail() helper to src/utils/validation.ts"
-  - category: complexity
-    file: "src/components/Dashboard.tsx"
-    lines: "120-245"
-    description: "Dashboard render function is 125 lines with 4 levels of nesting"
-    effort: standard
-    suggested_approach: "Extract stat cards, chart section, and filter bar into subcomponents"
-```
-
-## Step 3: Present Findings to User
-
-Group findings by category. Show each with:
-- File and line range
-- What the issue is
-- Estimated effort
-- Suggested approach
-
-Present top findings (max 10 initially). If there are more, mention the count.
-
-*"I found {N} refactoring opportunities in the code built during this milestone:"*
-
-Then for each category with findings:
-
-*"**Duplication** ({N} items):*
-*1. `src/api/users.ts:42-67` — Duplicate email validation in createUser and updateUser. Quick fix: extract shared helper. [Accept / Dismiss]*
-*2. ...*"
-
-## Step 4: User Triage
-
-The user can respond with:
-- **Accept** (individual item) → add to backlog
-- **Dismiss** (individual item) → skip, not a real issue or intentional
-- **Accept all** → bulk add all remaining items to backlog
-- **Dismiss all** → skip everything, no backlog items added
-
-For dismissed items, optionally ask for a brief reason (helps calibrate future scans).
-
-## Step 5: Write Backlog
-
-Read existing `.forge/refactor-backlog.yml` (if any). Determine the next item ID by incrementing from the highest existing ID.
-
-Append accepted items to `.forge/refactor-backlog.yml`:
-
-```yaml
-items:
-  - id: R001
-    milestone: 1
-    category: duplication
-    file: "src/api/users.ts"
-    lines: "42-67"
-    description: "Duplicate validation logic — same email check in createUser and updateUser"
-    effort: quick
-    suggested_approach: "Extract shared validateEmail() helper"
-    status: pending
-    added: "2026-03-18"
-    completed: null
-```
-
-If the file doesn't exist yet, create it from the template at `.forge/templates/refactor-backlog.yml`.
-
-Present summary:
-*"Added {N} items to the refactor backlog. {M} dismissed. You can work these anytime — pending items with `effort: quick` will show up as available Quick tasks when you start a session."*
-
-## Step 6: Route
-
-Update `.forge/state/milestone-{id}.yml`:
-- Set `current.status` to `complete`
-
-Update `.forge/state/index.yml`:
-- Set milestone status to `complete`
-- Update `last_updated` timestamp
-
-Present to user:
-*"Milestone [{name}] is complete. {N} refactoring items are in the backlog for whenever you want to tackle them."*
-
-If Beads is installed, run `bd complete` to update the dependency graph.
-
-## Gate Type: Soft Gate
-
-This is a soft gate — it presents opportunities but never blocks milestone completion. Rationale:
-- Refactoring is improvement, not correctness. The code already works (verified) and is healthy (audited).
-- Users should review opportunities but aren't forced to act on them immediately.
-- Backlog items persist across sessions and can be worked whenever it makes sense.
-- Some items may become irrelevant as the codebase evolves — that's fine.
-
-## Backlog Lifecycle
-
-Backlog items follow this lifecycle:
-
-```
-pending → in_progress → done
-pending → dismissed (during triage or later review)
-```
-
-Items with `effort: quick` can be picked up directly via `quick-tasking`.
-Items with `effort: standard` should go through the Standard tier flow.
-
-When working a backlog item:
-1. `forge` surfaces it as an available task
-2. User selects it
-3. Route to `quick-tasking` or Standard tier based on effort
-4. On completion, update the item's `status` to `done` and set `completed` date