# Blevesearch Bleve Bugfix

> Expert bug-fixing skills optimized for the blevesearch/bleve repository. Contains repo-specific patterns, diagnostic strategies, and step-by-step workflows for efficiently finding and resolving bugs in this codebase. Use when debugging issues, fixing failing tests, or resolving reported bugs.

- Skill: `gepa-ai/blevesearch-bleve-bugfix` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add gepa-ai/blevesearch-bleve-bugfix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gepa-ai/blevesearch-bleve-bugfix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: gepa-ai (https://skillmd.com/u/gepa-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/gepa-ai/blevesearch-bleve-bugfix

---


MERGED SKILL SET (Repo Bugfix / CI Container)

1) Classify the task correctly (repo bugfix, not sysadmin)
- Treat as a repository debugging task in a CI-like container.
- Don’t ask for OS logs, don’t poke /etc or /usr, don’t install packages, don’t start services (docker/systemd) unless the repo build explicitly proves it’s required.

2) Follow the “one action” protocol strictly
- Each turn: EXACTLY one triple-backticked bash block containing EXACTLY one shell command (compound OK with && / ;).
- Keep command output small (use head/tail/sed -n where relevant).
- Final step: output only `echo COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT`.

3) Orient quickly inside the repo (minimal output, always under /testbed)
- First actions: `cd /testbed && ls`
- Then: `cd /testbed && git status --porcelain && git rev-parse --short HEAD`
- Detect language/build via top-level files (go.mod, package.json, pyproject.toml, etc.).
- Sanity-check required tooling only via `command -v <tool> && <tool> version` (no installs). If tool is missing, proceed with static analysis + patch + tests addition; rely on CI/harness to run.

4) Run tests early and iterate from failures (tests are the bug report)
- Start broad when feasible: `cd /testbed && go test ./...` (or project equivalent).
- Narrow quickly:
  - package: `go test ./path/to/pkg`
  - single test: `go test ./path/to/pkg -run TestName -count=1` (add -v only if needed)
- For panics: follow the stack trace top frame in repo code first.
- For mismatches: use “expected vs got” to locate the producing function and invariants.

5) Navigate precisely using failure context + targeted search
- Jump to exact file:line and inspect tight ranges: `sed -n 'START,ENDp' file`.
- Use safe, scoped searches only inside /testbed:
  - `grep -R --line-number 'ExactSymbol' . --include='*.go' | head`
  - limit by likely directories/packages before broadening.
- Use Task ID as a hint: search exact token, then split/related terms.

6) Debug with domain-aware strategies (Go/token filters/stemmers as example)
- Don’t rewrite algorithms into simplistic “toy” logic; preserve intent and APIs.
- Look for classic Unicode/UTF-8 pitfalls:
  - byte indices mixed with rune counts
  - slicing mid-rune, len-based underflow, negative indices, unguarded len-k
- Fix by making indexing consistent (operate on []rune or maintain byte-safe indices via utf8 helpers), plus bounds guards as needed.

7) Make minimal, reviewable changes and verify continuously
- Change one behavior at a time; rerun the smallest reproducing test after each change.
- Add focused unit tests when coverage is missing; keep them in the same package and table-driven where sensible (include short words + accented/Unicode edge cases).
- Avoid scratch main.go files in repo root.

8) Go hygiene (when editing Go)
- Run `gofmt -w <files>` on touched files.
- Ensure imports are correct (no unused imports).
- Prefer preserving public interfaces; adjust internal logic unless tests demand API changes.

9) Patch hygiene before finishing
- Inspect changes: `cd /testbed && git diff`
- Don’t commit; leave working tree changes only.
- After fix, rerun broader tests (package then `./...`) if time permits.