Loop Polish

Loop Polish

Start project → Full verification → Scoring → Auto-fix → Loop until perfect → Generate report. Not perfect, don't ship.

---

1. Core Flow

Step 1 Start → Step 2 Verify → Step 3 Score → Step 4 Fix → Step 5 Regression → Step 6 Report
                ↑                                                     │
                └──────────── loop if not perfect ─────────────────────┘

Preflight mode: Step 1 → Step 2 → Step 3 → Output issues → Stop (no fix, no loop)

When to use: Explicitly requested loop polish, full integration verification with auto-fix, automated delivery acceptance. When NOT to use: Routine QA checks, simple bug reports, production environment validation, or when user only asked for a quick review.

---

2. Configuration .loop-polish.json (optional, defaults used if missing)

{
  "mode": "full",
  "max_rounds": 10,
  "target_score": 100,
  "scope": "all",
  "auto_fix": { "enabled": true, "strategy": "conservative", "max_per_round": 3 },
  "browser": { "headless": true },
  "db_verify": true,
  "report": { "format": "markdown", "output_dir": "./polish-reports/" },
  "timeout_minutes": 120
}

---

3. Execution Steps

Step 1: Start Project

0. Detect project structure:
   - Backend: search pom.xml/build.gradle/package.json/go.mod/requirements.txt
   - Frontend: search package.json + vite.config/vue.config/next.config
   - Pure frontend/backend: skip what doesn't exist, only start what's present

1. Git safety (full mode only):
   - Check workspace: git status --porcelain, stash uncommitted changes if any
   - Create fix branch: git checkout -b loop-polish/round-{timestamp}
   - Record original branch name for step 6 checkout

2. Clean up old processes (cross-platform):
   - Check ports: backend 8080/3000/5000, frontend 5173/3000
   - First, check if the process on the port belongs to this project (match project path in process command line)
   - Only kill if confirmed as project-owned. If port is occupied by an unrelated process, output warning and ask user before killing.
   - Windows: netstat -ano | findstr :port → check process path → taskkill /PID {pid} /F only if project-owned
   - Linux/Mac: lsof -ti :port → check process path → kill -9 only if project-owned

3. Start backend (if project has backend, by type):
   Java:   mvn clean package -DskipTests -q ; java -jar target/*.jar
   Node:   npm install ; node server.js
   Python: pip install -r requirements.txt ; python app.py
   Go:     go build ; ./app
   After startup, poll /health or /actuator/health or GET root path, up to 60s
   If none reachable, poll process port (netstat/lsof to confirm port is listening)

4. Start frontend (if project has frontend):
   npm install (if no node_modules) ; npm run dev
   Poll dev server up to 60s

5. Failure handling:
   → Capture error logs, attempt repair (missing deps/port conflicts), retry 2x → abort if still failing

---

Step 2: Full Verification

Scope control (by scope config):
  scope=all:      run 2.1 + 2.2 + 2.3
  scope=backend:  run 2.1 + 2.3
  scope=frontend: run 2.2
  scope=api:      run 2.1
  Pure frontend (no backend code): auto skip 2.1 and 2.3
  Pure backend (no frontend code): auto skip 2.2

2.1 Backend API Verification

1. Scan API endpoints:
   Java:   Grep @RestController to locate Controller files → Grep @(Get|Post|Put|Delete)Mapping within them
   Node:   Grep router\.(get|post|put|delete)|app\.(get|post|put|delete)
   Python: Grep @(app|router)\.(route|get|post|put|delete)
   Extract: HTTP method, path, parameter names and types

2. Parse request body params (POST/PUT):
   @RequestBody or body param points to DTO class → Read the DTO source → extract field names and types
   No DTO → extract from @RequestParam / @PathVariable in method signature

3. Path parameter handling (GET /users/{id} etc.):
   If mode=preflight: use GET list endpoint to obtain existing IDs, skip all POST/PUT/DELETE entirely.
   If mode=full: Call the module's POST to create a record → get the returned id → use for GET/PUT/DELETE path params
   If POST unavailable, try GET list endpoint → take first item's id
   If POST request body depends on other resources (e.g. creating order needs user ID), try creating dependency first, skip endpoint on failure

4. Auth handling:
   Scan endpoints with login/auth/signin keywords → auto call to get Token
   Subsequent requests auto carry Authorization: Bearer {token}
   Skip auth if no login endpoint found

5. Verify each endpoint (max 2 retries per endpoint):
   If mode=preflight: only test GET endpoints, skip POST/PUT/DELETE.
   Normal: valid params, verify 200/201 + response is valid JSON + key fields not empty
   Boundary: empty string, 0, negative, very long string
   Missing required: remove required field, verify 400
   Permission: no Token → 401, regular user Token on admin endpoint → 403

6. On failure, collect diagnostics:
   - Last 50 lines of backend log (tail -50 or Get-Content -Tail 50)
   - Response body + request params + request headers
   - Before saving to report or state file, REDACT sensitive fields:
     Authorization header → [REDACTED]
     Cookie header → [REDACTED]
     password/token/secret in request/response body → [REDACTED]
     Keep only error type, status code, and redacted summary for diagnostics.

2.2 Frontend Browser Verification

1. Scan frontend routes:
   Vue:  Grep "path:" to locate route file → extract all path values
   React: Grep "path:" or path: to locate route definitions → extract all paths
   Generate route list

2. Scan forms (from source, avoid blind operation):
   Grep " 2s or page load > 3s deducts points

Scoring formula:
  dimension_score = 100 × (passed_in_dimension / total_in_dimension)
  final_score = completeness×0.40 + correctness×0.25 + UX×0.15 + error_handling×0.10 + performance×0.10

Deduction: single point failure deducts 100/total points, retry still fails deducts extra 5 points (max 15)

Output format:

📊 Round 1: 76.8/100 [Not passed]
   Completeness:80%  Correctness:72%  UX:80%  Error:60%  Performance:90% | Passed:85/120  Failed:35

---

Step 4: Auto-fix

If auto_fix.enabled=false or mode=preflight: skip this step, go directly to step 6 to generate report

1. Fix priority (P1→P3):
   P1 Compile/syntax errors: missing import, type mismatch, null pointer
   P2 Logic/data errors: wrong query logic, wrong condition, frontend-backend mismatch
   P3 UX/performance: missing loading state, unfriendly messages (aggressive strategy only)

2. Strategy scope:
   conservative: P1~P2 | single file | ≤ 3 per round
   moderate:     P1~P2 | ≤ 2 files | ≤ 5 per round
   aggressive:   P1~P3 | cross-module | ≤ 10 per round

3. Fix flow:
   a. Read failed case diagnostic logs + screenshots → locate root cause → read source
   b. Generate fix plan (prefer minimal change)
   c. AskUserQuestion before high-risk changes (Schema change, auth logic, delete >10 lines)
   d. Save original code snippet before fix (for precise rollback on failure)
   e. Apply fix with Edit tool → record diff
   f. Local regression (only test this function point, not full run)
   g. Pass → mark fixed; Fail → restore original with Edit, mark "unfixable"

4. Exit strategy:
   - Same problem fails 2x → skip
   - 3 consecutive rounds with no score improvement → output "auto-fix limit reached", stop loop
   - Already conservative and 3 consecutive rounds with no improvement → stop immediately

Output format:

🔧 Round 1 fix (conservative):
  ✅ [P1] UserController.java:45 - missing @Valid
  ✅ [P1] order.ts:23 - path typo
  ⚠️ Skipped 2 need human confirmation | Fixed:2  Remaining:31

---

Step 5: Regression Verification

1. Retest only failed cases from previous round
2. git diff --name-only to detect changed files → only retest affected modules
3. Skip passed and unchanged modules
4. Run steps 2~3 → compare current round vs previous round score

Output format:

🔄 Round 2 regression: Retested 35 → Passed 31 Failed 4 | Score: 92.50 (+15.70 ↑)

---

Step 6: Termination & Report & Cleanup

Termination conditions (any one met):
  1. score >= target_score  → ✅ Passed
  2. rounds >= max_rounds   → ⏰ Max rounds reached
  3. 3 consecutive rounds score change < 1 → 📉 Score stagnated
  4. total time > timeout   → ⏱️ Timeout
  5. User interrupt

Report generation (output to report.output_dir):
  Do NOT include raw request/response bodies, auth tokens, or database credentials in reports.
  # Loop Polish Report
  ## Summary
  Final Score | Rounds | Total Time | Passed | Fixed | Remaining

  ## Score Trend
  | Round | Comp | Corr | UX | Err | Perf | Score | Change |

  ## Fix Details
  Per-round fix list + diff + outcome

  ## Remaining Issues + Recommendations
  Unfixed items + reasons + suggestions (add unit tests, add validation, add logging, etc.)

Cleanup:
  - Stop frontend and backend services (kill launched processes)
  - git checkout original branch
  - git stash pop (if stashed in step 1)
  - Output report path

---

4. Interrupt Recovery

Auto-save .loop-polish-state.json on interrupt:

{
  "round": 2, "step": "verify",
  "passed": ["api:GET:/users", "ui:login"], "failed": ["api:PUT:/orders"],
  "fixed": ["UserController.java:45"], "unfixable": [],
  "scores": [{"round":1,"score":76.8,"fixes":2}]
}

On resume: read state file → skip completed steps → continue from breakpoint. Delete this file to reset.

---

5. Usage Examples

Run loop polish                                    # Full polish
Loop polish preflight: API only                    # Quick scan
Loop polish: 5 rounds, 95 score, aggressive, HTML report  # Custom
Run loop polish on user module and order module, target 100  # Specific modules

---

6. Prerequisites

• Project is buildable and runnable
• npx playwright install chromium (auto-install on first run if missing)
• Database is connectable with initial data

---

7. Notes

• All fixes happen on isolated Git branches during the loop. After cleanup, review git status — stash pop may restore pre-existing uncommitted changes.
• Recommended strategy=conservative for first use, increase when comfortable
• Preflight mode is read-only (no data mutation), suitable for CI usage
• This skill terminates processes on target ports, reads database credentials, and modifies source code. Use in dev/staging environments only.
• Reports saved to polish-reports/ directory
• Auto checkout original branch and cleanup temp files when done