issue-driven-fix

name

issue-driven-fix

description

End-to-end loop for resolving GitHub issues empirically — review/triage issues, root-cause with codebase analysis, design and run live probes/experiments, analyze data, design a minimal evidence-driven solution, implement with tests, verify locally + re-probe live for regressions, deploy to the test harness, ship via branch→CI→merge→release, and report back on the issue. Use when asked to "review/work the issues", "investigate and fix", "run the workflow on issue N", or for any anti-bot/fingerprint/Cloudflare debugging that needs a real browser. Anchors on the Huey deploy harness for live validation.

Issue-Driven Fix Loop

A disciplined, empirical loop for turning GitHub issues into shipped, validated fixes. The governing principle: probe, don't guess — and re-probe after fixing. Most wasted effort in this repo's issue history came from plausible-but-wrong hypotheses that a single live measurement would have refuted.

Follow the phases in order. Skip a phase only when it's genuinely N/A, and say so.

Project anchors (verify before relying on)

• CLAUDE.md (root) defines coding standards — follow them exactly (package layout, error wrapping, defer cleanup, table-driven tests, no business logic in handlers, no hardcoded selectors).
• Code search: use ast-grep --pattern '...' for code patterns, rg/grep only for non-code text.
• Live harness: Huey = 192.168.50.185, user joe (key in ~/.ssh/config). Production flaresolverr on :8191 — do not disturb. Test container flaresolverr-invest on :8195. See the memory project-huey-deploy-harness for the exact build/deploy pattern. Local macOS can't drive a real browser well — use Huey for anything browser/fingerprint/Cloudflare.
• gh CLI is authorized for issues/PRs/releases/runs.

---

Phase 1 — Review & triage issues

gh issue list --state open --limit 30
gh issue view <N>; gh issue view <N> --comments

• Read the full thread including comments — prior commenters often already root-caused or refuted a path. Distinguish a confirmed code bug from an environmental/external wall (they need different handling; conflating them sends you down the wrong path).
• Triage outcome per issue: close as not-planned (with a documented reason) for external/won't-fix; keep open for actionable work; split an issue into the part that's fixable now vs the residual.
• When you post triage, quote the evidence and name what's ruled out.

Phase 2 — Root-cause analysis (codebase)

• Map the relevant code with ast-grep/Read. Trace the actual call paths (e.g. which stealth/solve path a request type takes — they often diverge).
• Form explicit competing hypotheses and, for each, the decisive check that would confirm or refute it.
• Build a model before measuring (e.g. "two stacked gates: IP tier vs fingerprint"). A wrong fix to the wrong gate looks busy and helps no one.
• Verify framework/library behavior against the actual vendored source (e.g. does go-rod call Runtime.enable?), not memory or blog lore.

Phase 3 — Design & run probes (live experiments)

This is the differentiator. Design experiments that isolate one variable each and run them against the live harness.

• Reuse scripts/probe_template.py (bundled with this skill) as the driver. It POSTs request.get with executeJs to dump structured JSON from a real page, and reads raw bodies (e.g. https://tls.peet.ws/api/all) for transport fingerprints.
• Build/deploy current code to flaresolverr-invest first so you measure shipped behavior, not a stale image:

  tar --exclude=.git -czf /tmp/fsg-invest.tgz -C <repo> .
  scp -q /tmp/fsg-invest.tgz joe@192.168.50.185:/tmp/
  ssh joe@192.168.50.185 'cd ~/flaresolverr-investigation && rm -rf ./* && \
    tar -xzf /tmp/fsg-invest.tgz -C . && docker build -q -t flaresolverr-go:investigation . && \
    docker rm -f flaresolverr-invest 2>/dev/null; \
    docker run -d --name flaresolverr-invest -p 8195:8191 -e LOG_LEVEL=debug -e RATE_LIMIT_ENABLED=false \
      flaresolverr-go:investigation'
  

• Use A/B probes to localize a defect (e.g. session path vs non-session path revealed which stealth layer shipped).
• Pick targets that reliably exhibit the phenomenon (e.g. nowsecure.nl reliably issues cf_clearance; a site that passes natively from a clean IP proves nothing about a stuck challenge).

Phase 4 — Analyze the data

• State what each probe confirmed and ruled out. Ruling things out is as valuable as finding the bug — it stops the whole thread chasing a dead vector.
• Reduce to concrete, named defects with evidence (file:line + measured value), ranked by signal strength.

Phase 5 — Design the solution

• Minimal and surgical. Prefer the smallest change that fixes the measured defect over a broad rewrite. (Layering an entire stealth script caused regressions; a 2-fix targeted patch didn't.)
• Respect couplings (e.g. a cache keyed by an identity must move in lockstep with whatever sets that identity).
• Be honest about the value ceiling: if a fix can't help the reported case (gated by something else), say so and pick the path with real, testable payoff.

Phase 6 — Implement

• Follow CLAUDE.md. Accept interfaces / return structs, context first, defer every acquire, bound every buffer/map, sentinel/wrapped errors, no naked goroutines.
• Add table-driven unit tests next to the code for every new component. Make time/randomness injectable for deterministic tests.

Phase 7 — Verify (local + live re-probe)

go build ./... && go vet ./... && go test -short ./internal/<pkg>/...

• Then re-deploy and re-probe. Confirm the target metric flipped AND run a regression probe (e.g. sannysoft all-pass) — a fix on the hot path can silently break an adjacent property. Empirical re-validation has caught real regressions a green build did not.
• For config/CI changes, validate with the real tool, not assumption (e.g. goreleaser check, install the exact version CI floats to).

Phase 8 — Deploy / end-to-end

• Run a real end-to-end action through the harness (e.g. an actual CF solve) to confirm the change didn't break the happy path. Capture timing/cookies/logs as evidence.
• Tear down any scratch infra you stood up (test proxies, containers).

Phase 9 — Ship

• Branch from main (never commit straight to default): git checkout -b <type>/<slug>.
• Commit with a body explaining the measured finding + fix; end with: Co-Authored-By: Claude Opus 4.8 (1M context) <[e-mail]>
• Push, watch CI to green (gh run watch <id> --exit-status), then merge (--no-ff to main), push main, delete the branch (local + remote).
• For a release: bump CHANGELOG [Unreleased]→[x.y.z], tag vX.Y.Z (semver: features→minor), push the tag, and watch the Release + Docker workflows. Verify the GitHub release assets and Docker tags exist.

Phase 10 — Report on the issue

• Post a structured comment: what was ruled out (with the data), what was fixed (with validation evidence), honest scope (what it does and doesn't do), and what residual remains.
• Tag thread participants. Ask for the one data point you can't generate (e.g. "test with a residential PROXY_LIST").
• Update memory (MEMORY.md + a project-* file) with non-obvious findings and ruled-out vectors so the next session doesn't re-investigate.

---

Anti-patterns (seen in this repo's history)

• Shipping an anti-bot change without a live repro/validation — the class of change that most needs it.
• "Improve the TLS layer" / "patch the Runtime.enable leak" cargo-culted from blogs without checking they apply (they didn't here — measured).
• A green go build treated as proof a fingerprint/behavioral change works — it isn't; re-probe.
• Broad fixes that regress adjacent properties; prefer surgical.
• Over-claiming in issue comments; state the value ceiling plainly.