bq-inspector 0.1.0__tar.gz

bq_inspector-0.1.0/.agents/skills/build-and-fix/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: build-and-fix
+description: Build the project and automatically fix packaging or build errors (for example Hatch failures) and related breakage. Use when the project fails to build, shows "broken" states, or after making significant changes.
+---
+
+# Build and Fix Loop
+
+## Purpose
+
+An autonomous loop for the agent to identify, analyze, and fix build errors using `make build`.
+
+## Loop Logic
+
+1. **Identify**: Run `make build` to identify build failures.
+2. **Analyze**: Examine the build output to determine:
+   - The failing component (e.g., `hatch` build error).
+   - The specific error message (e.g., missing dependencies, syntax errors, packaging issues).
+   - For `make` / `uv` commands, see the project root [CLAUDE.md](../../../CLAUDE.md).
+3. **Fix**: Apply the minimum necessary change to resolve the error (e.g., updating `pyproject.toml`, fixing syntax, or adding missing files).
+4. **Verify**: Re-run `make build`.
+   - If passed: Finish.
+   - If failed: Analyze the new failure and repeat the loop.
+
+## Termination Criteria
+
+- The project builds successfully (as reported by `make build`).
+- Reached max iteration limit (default: 5).
+- The error persists after multiple distinct fix attempts, indicating a need for human intervention.
+
+## Examples
+
+### Scenario: Fixing a packaging error
+
+1. `make build` fails because of a missing dependency in `pyproject.toml`.
+2. Agent analyzes the error, adds the dependency using `uv add`.
+3. `make build` now passes.
+
+## Resources
+
+- [Hatch Documentation](https://hatch.pypa.io/): Official documentation for the Hatch build backend.

bq_inspector-0.1.0/.agents/skills/check-directory-structure/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: check-directory-structure
+description: Inspect repository layout with tree and find, compare to AGENTS.md conventions, and fix misplaced or overly flat generated files. Use when auditing folder structure, after scaffolding or bulk file generation, when output looks flat, or when asked where code/tests/docs should live. Supports inspecting the repository root or a specified subdirectory.
+compatibility: Unix-like shell. POSIX find required; optional tree for readability (install via OS package manager if missing). Run from inside the working tree; set TARGET to the directory to inspect (default `.` for the current directory, often the repo root after `cd`).
+---
+
+# Check directory structure
+
+## Purpose
+
+Ground work in the **actual** on-disk layout and catch **flat or misplaced** output (for example many new files at the repository root) before finishing a task.
+
+## When to use
+
+- After scaffolding, renaming the package, or generating several new files
+- When imports or paths feel wrong compared to where files really live
+- When the user asks where code, tests, or scripts should live
+- When output looks like a **flat dump** instead of nested package layout
+
+## How to run
+
+Read **Architecture** and testing layout in [`AGENTS.md`](../../../AGENTS.md). Resolve the real package name from `pyproject.toml` / `src/` on disk (the template uses `your_package` until [`initialize-project`](../../../.claude/skills/initialize-project/SKILL.md) runs).
+
+**Target directory:** By default, inspect the **current directory** (after `cd` to the repository root, that is the whole repo). To inspect only a subtree—for example a package or feature folder—set `TARGET` to that path (repo-relative or absolute). Examples: `TARGET=.` (same as root after `cd` to repo root), `TARGET=src/your_package`, `TARGET=dev`. Use the same `TARGET` in every command below.
+
+```bash
+# From repository root; inspect whole repo
+TARGET=.
+
+# Or inspect only a subtree (repo-relative or absolute path)
+TARGET=src/your_package
+```
+
+### 1. Snapshot layout
+
+**Optional — readable tree** (skip if `tree` is not installed):
+
+```bash
+tree -L 3 -a -I '.git|__pycache__|.venv|node_modules|dist|build|.pytest_cache|.ruff_cache' "${TARGET:-.}"
+```
+
+**POSIX `find` — works without `tree`:** run from inside `TARGET` so skipping `.git`, `.venv`, and `__pycache__` works for both the repo root and a subdirectory.
+
+```bash
+# Immediate children of TARGET (plus `.` for the root of the scanned tree)
+(cd "${TARGET:-.}" && find . \( -name '.git' -o -name '.venv' -o -name '__pycache__' \) -prune -o -maxdepth 1 -print)
+
+# Sample of files under TARGET (cap output on large trees)
+(cd "${TARGET:-.}" && find . \( -name '.git' -o -name '.venv' \) -prune -o \( -type d -name '__pycache__' \) -prune -o -type f -print | head -200)
+```
+
+**Optional — depth signal** (rough hint for flat vs nested paths under `TARGET`):
+
+```bash
+(cd "${TARGET:-.}" && find . -type f -print | awk -F/ '{ print NF-1 }' | sort -n | tail -5)
+```
+
+If `TARGET` is not the repository root, map what you see back to the **full** repo layout in [`AGENTS.md`](../../../AGENTS.md) (for example `src/<package>/` vs `dev/`).
+
+### 2. Compare to this repository
+
+- **Package code** lives under `src/<package>/`, not loose Python modules at the repository root.
+- **Tests** live under `src/<package>/tests/`; files match `test_*.py` (see [`AGENTS.md`](../../../AGENTS.md)).
+- **Dev scripts:** `dev/`; **CI:** `.github/workflows/`; **ADRs:** `docs/adr/` when used.
+
+If the tree still shows `your_package` but the project should use a real name, follow [`initialize-project`](../../../.claude/skills/initialize-project/SKILL.md).
+
+### 3. Fix loop
+
+1. **Move** misplaced files to match the conventions above.
+2. **Update** imports, packaging paths in `pyproject.toml`, and references in docs or CI if paths changed.
+3. **Verify** with `make lint && make test` per [`AGENTS.md`](../../../AGENTS.md).
+
+## Termination
+
+- Layout matches documented conventions, or
+- Remaining differences are **explicitly accepted** with a short rationale, or
+- After **2** relocate/fix iterations, stop and list remaining items for the user.
+
+## Related
+
+- [`AGENTS.md`](../../../AGENTS.md) — Architecture, testing, quick commands
+- [`CLAUDE.md`](../../../CLAUDE.md) — Claude Code entrypoint and `.claude/` layout
+- [`initialize-project`](../../../.claude/skills/initialize-project/SKILL.md) — Rename template package and bootstrap

bq_inspector-0.1.0/.agents/skills/codeql-fix/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: codeql-fix
+description: Run CodeQL security/quality analysis and fix findings. Use when the user asks to run CodeQL, security scan, static analysis, or fix CodeQL findings.
+compatibility: Requires [CodeQL CLI](https://github.com/github/codeql-cli-binaries/releases) on PATH via `make setup-tools` or mise (`mise.toml`). Python and [uv](https://github.com/astral-sh/uv) aligned with [`.python-version`](../../../.python-version) and [`pyproject.toml`](../../../pyproject.toml). Run `uv sync` or `make setup` before analysis when findings should reflect installed dependencies (matches [`.github/workflows/codeql.yml`](../../../.github/workflows/codeql.yml)).
+---
+
+# CodeQL Fix
+
+Use when the user asks to run CodeQL or static analysis, or to fix CodeQL findings (see frontmatter `description`).
+
+## Preconditions
+
+- [CodeQL CLI](https://github.com/github/codeql-cli-binaries/releases) on `PATH` via **`make setup-tools`**, **`make codeql`** (`mise run codeql`), or **`mise install --locked`** per `mise.toml`.
+- Install project deps before creating the database (`uv sync`, `make setup`, or CI-style `uv sync --frozen`) so results match installed dependencies.
+
+## Run analysis (repository root)
+
+All commands below assume `cd "$(git rev-parse --show-toplevel)"`.
+
+Do not commit CodeQL databases or SARIF outputs (large, machine-specific). They belong in [`.gitignore`](../../../.gitignore) (for example `.codeql_db/`, `codeql-results.sarif`).
+
+### 1. Preferred: Makefile (matches [`dev/codeql.sh`](../../../dev/codeql.sh))
+
+```bash
+make codeql
+```
+
+This creates **`.codeql_db`**, analyzes with **`codeql/python-queries:codeql-suites/python-security-and-quality.qls`**, writes **`codeql-results.sarif`**, and passes **`--download`** to resolve query packs.
+
+### 2. Manual CLI (equivalent to the script)
+
+Create the database (Python needs no build command for extraction):
+
+```bash
+codeql database create .codeql_db --language=python --source-root . --overwrite
+```
+
+Analyze and emit SARIF:
+
+```bash
+codeql database analyze .codeql_db \
+  "codeql/python-queries:codeql-suites/python-security-and-quality.qls" \
+  --format=sarif-latest \
+  --output=codeql-results.sarif \
+  --download
+```
+
+- For a narrower suite closer to default GitHub code scanning, use `codeql/python-queries:codeql-suites/python-code-scanning.qls` instead.
+- If packs are missing and you are not using `--download`, run `codeql pack download codeql/python-queries` once.
+
+View SARIF in the VS Code SARIF extension (or upload where your org uses code scanning).
+
+### 3. Optional: code scanning config (`paths-ignore`)
+
+Use the renderer when you want `paths-ignore` for large or generated trees, hand-edited query blocks, or parity with GitHub code scanning YAML.
+
+```bash
+REPO="$(git rev-parse --show-toplevel)"
+"$REPO/.claude/skills/codeql-fix/scripts/render-code-scanning-config.sh" "$REPO" /tmp/codeql-config.yml
+codeql database create .codeql_db --language=python --source-root . --codescanning-config=/tmp/codeql-config.yml --overwrite
+```
+
+Then run `codeql database analyze` as in section 2. See [references/code-scanning-config.md](references/code-scanning-config.md).
+
+## Fixer loop
+
+If the relevant SARIF has an empty `runs[].results` array, there are **no CodeQL alerts to fix** for that suite; stop unless the user wants a broader suite or diagnostic queries.
+
+When SARIF findings remain:
+
+1. **Identify:** Read the SARIF or CLI output for reported findings.
+2. **Fix:** Apply the minimum necessary edit to resolve each finding.
+3. **Verify:** From the repository root, run `make test`, then `make lint` (see [AGENTS.md](../../../AGENTS.md) and the [Makefile](../../../Makefile); `make lint` runs `trunk check -a`).
+4. **Re-scan:** Run `make codeql` or repeat the manual create + analyze steps until clean or up to 3 iterations to avoid unbounded loops.
+
+## Optional: code scanning config details
+
+See [references/code-scanning-config.md](references/code-scanning-config.md) and the official [code scanning configuration](https://aka.ms/code-scanning-docs/config-file) reference.

bq_inspector-0.1.0/.agents/skills/codeql-fix/assets/code-scanning-config.template.yml

@@ -0,0 +1,17 @@
+# Code scanning configuration (template — do not pass this file directly to codeql).
+# Render a repo-specific file with: scripts/render-code-scanning-config.sh
+#
+# Skill reference: ../references/code-scanning-config.md (from this template file)
+# Official schema and fields: https://aka.ms/code-scanning-docs/config-file
+#
+# The renderer replaces the "name:" line and appends "paths-ignore" when needed.
+# After rendering, you may hand-edit the output (e.g. query suites) before
+# codeql database create --codescanning-config=<file>
+#
+# Optional: enable a query suite in the generated file (examples — uncomment in output):
+# queries:
+#   - uses: security-extended
+#   - uses: security-and-quality
+#
+# Placeholder name — replaced by render-code-scanning-config.sh (or override via CODEQL_CONFIG_NAME)
+name: local-codeql

bq_inspector-0.1.0/.agents/skills/codeql-fix/references/code-scanning-config.md

@@ -0,0 +1,12 @@
+# Code scanning config (template + renderer)
+
+This skill ships a YAML template and a small shell renderer under the same directory as [`SKILL.md`](../SKILL.md).
+
+- **Template:** [`assets/code-scanning-config.template.yml`](../assets/code-scanning-config.template.yml)
+- **Renderer:** [`scripts/render-code-scanning-config.sh`](../scripts/render-code-scanning-config.sh)
+
+Local CodeQL in this repository is **CLI-driven** for **Python**: primary extraction uses `codeql database create` with `--language=python` and `--source-root .` (no build command). See [`SKILL.md`](../SKILL.md) and [`dev/codeql.sh`](../../../../dev/codeql.sh) for the full `database create` / `database analyze` flow.
+
+When `CODEQL_CONFIG_REPO_SCAN` is enabled (default), the renderer adds common noise paths if present (for example `.git`, `node_modules`, `.codeql_db`, virtualenvs, Python caches, coverage output). It intentionally stays minimal for this template; use comma-separated **`CODEQL_PATHS_IGNORE`** (and optional extra CLI arguments to the script) for monorepo build dirs, e2e artifacts, Terraform caches, or other repo-specific trees.
+
+Pass the rendered file to `codeql database create --codescanning-config=<file>` when you need `paths-ignore` or other [code scanning configuration](https://aka.ms/code-scanning-docs/config-file) options beyond a bare `--source-root .` create.

bq_inspector-0.1.0/.agents/skills/codeql-fix/scripts/render-code-scanning-config.sh

@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+# Render Code Scanning YAML from assets/code-scanning-config.template.yml for a repository.
+# Merges CODEQL_PATHS_IGNORE, extra CLI paths, and optional existence-based paths-ignore
+# tuned for this Python template. Add monorepo/e2e paths via CODEQL_PATHS_IGNORE or by
+# extending the scan block below.
+# Docs: https://aka.ms/code-scanning-docs/config-file
+set -euo pipefail
+
+usage() {
+	echo "Usage: $0 <repo-root> <output-yaml> [extra-path-to-ignore ...]" >&2
+	echo "Env: CODEQL_CONFIG_NAME (override name), CODEQL_PATHS_IGNORE (comma-separated)," >&2
+	echo "     CODEQL_CONFIG_REPO_SCAN=0|false to skip auto paths-ignore from repo layout" >&2
+	exit 2
+}
+
+[[ $# -ge 2 ]] || usage
+REPO=$(cd "$1" && pwd)
+OUT="$2"
+shift 2
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+SKILL_ROOT=$(cd "${SCRIPT_DIR}/.." && pwd)
+TEMPLATE="${SKILL_ROOT}/assets/code-scanning-config.template.yml"
+
+if [[ ! -f ${TEMPLATE} ]]; then
+	echo "Missing template: ${TEMPLATE}" >&2
+	exit 1
+fi
+
+CONFIG_NAME=${CODEQL_CONFIG_NAME-}
+if [[ -z ${CONFIG_NAME} ]]; then
+	if top=$(git -C "${REPO}" rev-parse --show-toplevel 2>/dev/null); then
+		CONFIG_NAME=$(basename "${top}")
+	else
+		CONFIG_NAME=local-codeql
+	fi
+fi
+
+paths_tmp=$(mktemp)
+tmp_out=$(mktemp)
+cleanup() {
+	rm -f "${paths_tmp}" "${tmp_out}"
+}
+trap cleanup EXIT
+
+add_path() {
+	local p="${1//[$'\t\r\n']/}"
+	# Trim leading/trailing whitespace without spawning sed.
+	p="${p#"${p%%[![:space:]]*}"}"
+	p="${p%"${p##*[![:space:]]}"}"
+	[[ -z ${p} ]] && return
+	if [[ -s ${paths_tmp} ]] && grep -Fxq "${p}" "${paths_tmp}" 2>/dev/null; then
+		return
+	fi
+	echo "${p}" >>"${paths_tmp}"
+}
+
+if [[ -n ${CODEQL_PATHS_IGNORE-} ]]; then
+	IFS=',' read -r -a _parts <<<"${CODEQL_PATHS_IGNORE}"
+	for p in "${_parts[@]}"; do
+		add_path "${p}"
+	done
+fi
+
+for p in "$@"; do
+	add_path "${p}"
+done
+
+_scan=${CODEQL_CONFIG_REPO_SCAN:-1}
+if [[ ${_scan} == "1" || ${_scan} == "true" ]]; then
+	[[ -d "${REPO}/node_modules" ]] && add_path "node_modules"
+	[[ -d "${REPO}/.git" ]] && add_path ".git"
+	[[ -d "${REPO}/dist" ]] && add_path "**/dist"
+	[[ -d "${REPO}/coverage" ]] && add_path "coverage"
+	[[ -d "${REPO}/htmlcov" ]] && add_path "htmlcov"
+	[[ -d "${REPO}/.pytest_cache" ]] && add_path ".pytest_cache"
+	[[ -d "${REPO}/.ruff_cache" ]] && add_path ".ruff_cache"
+	[[ -d "${REPO}/codeql-db" ]] && add_path "codeql-db"
+	[[ -d "${REPO}/.codeql_db" ]] && add_path ".codeql_db"
+	add_path "**/.venv"
+fi
+
+if [[ -s ${paths_tmp} ]]; then
+	sort -u "${paths_tmp}" -o "${paths_tmp}"
+fi
+path_count=0
+if [[ -s ${paths_tmp} ]]; then
+	path_count=$(wc -l <"${paths_tmp}")
+	path_count=${path_count// /}
+fi
+
+{
+	while IFS= read -r line || [[ -n ${line-} ]]; do
+		if [[ ${line} =~ ^name:[[:space:]] ]]; then
+			echo "name: ${CONFIG_NAME}"
+		else
+			printf '%s\n' "${line}"
+		fi
+	done <"${TEMPLATE}"
+
+	if [[ ${path_count} -gt 0 ]]; then
+		echo "paths-ignore:"
+		while IFS= read -r p || [[ -n ${p-} ]]; do
+			[[ -z ${p-} ]] && continue
+			# Quote values so YAML does not treat '*' (e.g. **/.venv) as alias syntax.
+			_esc=${p//\\/\\\\}
+			_esc=${_esc//\"/\\\"}
+			printf '  - "%s"\n' "${_esc}"
+		done <"${paths_tmp}"
+	fi
+} >"${tmp_out}"
+
+mv "${tmp_out}" "${OUT}"
+trap - EXIT
+rm -f "${paths_tmp}"
+echo "Wrote ${OUT}" >&2

bq_inspector-0.1.0/.agents/skills/deep-problem-solving/README.md

@@ -0,0 +1,19 @@
+# Deep Problem Solving
+
+Companion README for [`SKILL.md`](SKILL.md). Interactive decision support: deep framing, then **exactly ten** multiple-choice questions (one per turn), then a scored comparison and recommendation. Output uses [`references/full-report-template.md`](references/full-report-template.md).
+
+## Triggers (examples)
+
+- “Don’t jump to a solution—ask me questions first, then compare options with scores.”
+- High-stakes architecture or strategy where priorities need to be elicited before scoring.
+
+## Layout
+
+```text
+deep-problem-solving/
+├── SKILL.md
+├── README.md
+└── references/full-report-template.md
+```
+
+This repository may ship other skills under [`.claude/skills/`](..); pick the skill whose frontmatter **description** matches your task. Routing for decision-support variants is summarized in [AGENTS.md](../../../AGENTS.md) (Claude Code skills table).

bq_inspector-0.1.0/.agents/skills/deep-problem-solving/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: deep-problem-solving
+description: |
+  Interactive deep research and decision support: frame the real problem (XY-aware), ask exactly 10 multiple-choice questions one at a time, then produce a rigorous comparative evaluation (default 5 approaches, 0–100 scores) and recommendation.
+  Use when the user wants structured discovery before committing to a solution, a scored comparison of approaches, or to avoid jumping straight to an answer—especially for architecture, strategy, or high-stakes trade-offs.
+---
+
+# Deep Problem Solving (Interactive Deep-Research Solution Evaluator)
+
+## Relationship to single-pass analysis
+
+Another mode in this repo is a **single-pass** XY-aware analysis and scored comparison (no mandatory question phase). **This skill adds Phase 1 framing, then exactly ten interactive questions (one per user turn), then Phase 3 evaluation.** Do not skip Phase 2. Do not emit the final report until Phase 2 is complete unless the user explicitly stops early.
+
+## Role
+
+You are an expert research and decision-support assistant. Help the user identify the real problem, explore the solution space interactively, then produce a rigorous comparative recommendation. **Do not jump straight to solutions.**
+
+## Required workflow
+
+Follow this sequence exactly.
+
+### Phase 1 — Deep research and problem framing
+
+Before proposing any solution, analyze the situation broadly and deeply. **Do not generate final recommendations in this phase.**
+
+Your analysis must include:
+
+1. **Stated Problem (X)** — What the user explicitly asked for.
+2. **Underlying Intent (Y)** — The deeper goal they are actually trying to achieve.
+3. **XY problem check** — Test whether X is only an intermediate step, an assumed constraint, or a potentially suboptimal path to Y. If so, say so clearly and explain why.
+4. **Context expansion** — Surrounding constraints, assumptions, dependencies, risks, stakeholders, trade-offs, and failure modes.
+5. **Research depth** — Consider multiple angles where relevant (technical, operational, strategic, UX, maintainability, performance, security, cost, scalability, compliance, time-to-deliver).
+
+### Phase 2 — Ten interactive questions, one per turn
+
+After Phase 1, ask **exactly 10 questions**, **one per turn**, to refine direction before the final evaluation.
+
+Rules:
+
+1. Ask **only one question per turn**.
+2. Each question must include **multiple answer options** (prefer **3 to 6**).
+3. Include **Other / Explain** when helpful.
+4. Each question should narrow priorities, constraints, preferences, risk tolerance, timeline, budget, quality bar, architecture direction, success criteria, or acceptable trade-offs.
+5. **Adapt** later questions based on earlier answers.
+6. Do not skip ahead. Do not provide the final report until all 10 questions are answered, unless the user explicitly asks to stop early.
+7. Keep questions concise; make options concrete and decision-useful.
+8. After each answer, **briefly acknowledge** it, then ask the next question.
+
+**Question format** (use every time):
+
+```text
+**Question {N}/10: [short title]**
+[One concise sentence explaining what is being decided.]
+
+A. [Option A]
+B. [Option B]
+C. [Option C]
+D. [Option D]
+E. [Optional: Other / Explain]
+```
+
+**Platform:** If the environment offers a multiple-choice or structured question UI, use it with the same options. Otherwise use plain text as above.
+
+### Phase 3 — Full structured evaluation
+
+After Question 10 is answered (or the user stopped early), proceed:
+
+1. **Analyze intent and issue** — Stated X, underlying Y, XY check, context and impact (root causes, system implications, trade-offs, downstream effects).
+2. **Determine approaches** — Generate **n** distinct approaches that satisfy **Y**, default **n = 5** (or the user’s number). Include approaches that solve Y directly even if they bypass X.
+3. **Define scoring criteria** — Tailor to the problem and to Phase 2 answers (e.g. feasibility, complexity, speed, cost, performance, maintainability, security, scalability, reliability, compliance, user impact, reversibility, operational burden). Use only relevant criteria.
+4. **Score approaches** — For each criterion, score each approach **0–100**. Be explicit and consistent; justify non-obvious scores; avoid inflation; reflect Phase 2 priorities; state high uncertainty when needed.
+5. **Recommend** — Choose the best approach using intent alignment, score profile, critical trade-offs, constraints, and long-term consequences. Also cover: when the top-scoring option may **not** be best in practice; assumptions that could change the recommendation; a strong second choice under different constraints.
+
+## Final report
+
+After Phase 2 is complete, generate the report using the structure in [references/full-report-template.md](references/full-report-template.md).
+
+## Behavioral rules
+
+- Do not rush. Do not assume the user’s first framing is correct.
+- Do not skip the 10-question phase (unless the user explicitly ends it early).
+- Do not ask all 10 questions in one message.
+- Do not deliver the final recommendation report before the questioning phase is finished, unless the user explicitly requests an early stop.
+- Challenge flawed premises when evidence supports it. Optimize for the user’s real objective, not only their first requested method.
+- Prefer clarity, rigor, and practical usefulness over superficial completeness.
+
+## Start condition
+
+When this skill is activated:
+
+1. Perform the Phase 1 framing analysis **internally** (you may show a concise version to the user as part of the opening).
+2. Briefly summarize **Stated Problem (X)**, **Underlying Intent (Y)**, and **possible XY risk**.
+3. Immediately ask **Question 1/10** with answer options.
+4. **Do not** generate the full final report yet.
+
+## Examples
+
+**User:** “We need to move off our self-hosted Redis.”
+
+**Agent:** Short summary of X (migrate Redis) vs Y (reliability, ops cost, etc.) and XY note if applicable → **Question 1/10** with options (e.g. managed Redis vs memory store vs redesign cache layer, etc.).

bq_inspector-0.1.0/.agents/skills/deep-problem-solving/references/full-report-template.md

@@ -0,0 +1,75 @@
+<!-- Report template for interactive discovery (ten-question phase before scoring). -->
+
+# Intent & Issue Analysis Report
+
+## 1. Intent & Issue Analysis
+
+### Stated Problem (X)
+
+<!-- What the user explicitly asked for. -->
+
+### Underlying Intent (Y)
+
+<!-- The deeper goal the user is likely trying to achieve. -->
+
+### XY Problem Check
+
+<!-- Explicit analysis of whether X is distracting from or inferior to solving Y directly. -->
+
+### Context & Impact
+
+<!-- Deep analysis of context, assumptions, constraints, root causes, and likely impacts. -->
+
+## 2. Evaluation Criteria
+
+<!-- List and define the criteria used for scoring, tailored to the user's situation and Phase 2 answers. -->
+
+## 3. Approaches
+
+<!-- Default: n = 5. Adjust headings if the user requested a different n. -->
+
+### Approach 1: [Name]
+
+- **Description**:
+- **Pros**:
+- **Cons**:
+
+### Approach 2: [Name]
+
+- **Description**:
+- **Pros**:
+- **Cons**:
+
+### Approach 3: [Name]
+
+- **Description**:
+- **Pros**:
+- **Cons**:
+
+### Approach 4: [Name]
+
+- **Description**:
+- **Pros**:
+- **Cons**:
+
+### Approach 5: [Name]
+
+- **Description**:
+- **Pros**:
+- **Cons**:
+
+## 4. Scoring Matrix
+
+| Approach   | [Criterion 1] | [Criterion 2] | [Criterion 3] | [Criterion 4] | Average |
+| :--------- | :-----------: | :-----------: | :-----------: | :-----------: | :-----: |
+| Approach 1 |               |               |               |               |         |
+| Approach 2 |               |               |               |               |         |
+| Approach 3 |               |               |               |               |         |
+| Approach 4 |               |               |               |               |         |
+| Approach 5 |               |               |               |               |         |
+
+_Scores are from 0 to 100._
+
+## 5. Recommendation
+
+<!-- Final recommendation, reasoning, trade-offs, caveats, when top score may not be best, assumptions that could change the pick, and second-best under different constraints. -->

bq_inspector-0.1.0/.agents/skills/initialize-project/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: initialize-project
+description: Initialize a new project from the Python template by renaming packages, updating metadata, and cleaning up documentation. Use when starting a new project, "bootstrapping" from this template, or setting up a fresh repository.
+---
+
+# Initialize Project
+
+## Purpose
+
+This skill automates the initial setup of a new project derived from this template. It leverages AI capabilities to directly modify project metadata and documentation by replacing placeholders, ensuring a clean start for a new repository.
+
+## Instructions
+
+1. **Gather Information**: Ask the user for:
+   - New project name (e.g., `my-awesome-app`)
+   - Project description
+   - Author name (e.g., `Your Name <your.email@example.com>`)
+2. **Update Project Metadata**: Directly update the following files using the `Write` or `StrReplace` tools:
+   - `pyproject.toml`: Update `project.name`, `project.description`, and `project.authors`.
+   - Update `tool.hatch.build.targets.wheel.packages` to match the new source directory.
+3. **Rename Source Package**:
+   - Rename `src/your_package` to the new package name (e.g., `src/my_awesome_app`).
+   - Update any internal imports if they reference `your_package`.
+4. **Update README Placeholders**: Use the `StrReplace` tool to replace the placeholders in `README.md` with the gathered information:
+   - `{PROJECT_NAME}` -> New project name
+   - `{PROJECT_DESCRIPTION}` -> Project description
+5. **Install Dependencies**: Run `make setup` to initialize the environment and update `uv.lock`.
+6. **Final Cleanup**: Remove the initialization skill and its related files once bootstrapping is complete, if requested by the user.
+
+## Examples
+
+### Example 1: Initializing a new CLI tool
+
+**Input**: User says "Initialize this project as 'json-fixer', a CLI tool to fix broken JSON files."
+**Action**:
+
+1. Gather details from the user (Name: json-fixer, Description: A CLI tool to fix broken JSON files, Author: [Author Name]).
+2. Update `pyproject.toml` with the new metadata.
+3. Rename `src/your_package` to `src/json_fixer`.
+4. Use `StrReplace` on `README.md` to swap placeholders with actual values.
+5. Run `make setup`.

bq_inspector-0.1.0/.agents/skills/lint-and-fix/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: lint-and-fix
+description: Run linters and fix violations, formatting errors, or style mismatches using Trunk. Use when code quality checks fail, before submitting PRs, or to repair "broken" linting states.
+---
+
+# Lint and Fix Loop: Trunk
+
+## Purpose
+
+An autonomous loop for the agent to identify, fix, and verify linting and formatting violations using [Trunk](https://trunk.io), plus dead-code detection with [Vulture](https://github.com/jendrikseipp/vulture).
+
+## Trunk CLI resolution
+
+`make lint` and `make format` delegate to **`mise run lint`** and **`mise run format-trunk`** (see `mise.toml`). Resolve Trunk **once** at the start of the loop:
+
+1. After **`make setup-tools`** (or `mise install --locked`), prefer **`make lint`** / **`make format`** so mise activates the pinned `trunk` from `mise.lock`.
+2. If `trunk` is on `PATH` (`command -v trunk`), you may also call `trunk check -a` / `trunk fmt -a` directly (same as `mise run lint` / `mise run format-trunk` when shims are active).
+3. Otherwise use the NPM launcher: **`npx --yes @trunkio/launcher`** with the same subcommands (for example `npx --yes @trunkio/launcher check -a`, `npx --yes @trunkio/launcher fmt -a`, `npx --yes @trunkio/launcher install`).
+4. If Trunk reports missing managed tools, run **`mise run trunk-install`** or **`make setup-tools`** (or the `npx … install` form above) per [AGENTS.md](../../../AGENTS.md).
+
+When `trunk` is missing from `PATH` and mise is not installed, prefer explicit **`npx --yes @trunkio/launcher …`** over `make lint` / `make format`.
+
+## Loop Logic
+
+1. **Identify**:
+   - Run **`make lint`** (**`mise run lint`**, Trunk `check -a`) **or**, when Trunk is unavailable, **`npx --yes @trunkio/launcher check -a`**.
+   - Run **dead-code detection**: **`make dead-code`** (alias **`make vulture`**, runs **`uv run vulture`** using `[tool.vulture]` in `pyproject.toml`). Fix unused code the tool reports by removing it or wiring it into real usage—do not silence Vulture with broad excludes unless the user asked for that policy change.
+2. **Analyze**: Examine the output from Trunk and Vulture, focusing on the file path, line number, and error message.
+3. **Fix**:
+   - For formatting issues, run **`make format`** (**`mise run format-trunk`** plus `uv run ssort`) **or** **`npx --yes @trunkio/launcher fmt -a`** when using the NPM launcher.
+   - For linting violations, apply the minimum necessary change to the source code to resolve the error.
+   - Resolve findings by changing code, types, imports, or structure—not with suppressions (see **Constraints**).
+4. **Verify**:
+   - Re-run **`make lint`** / **`npx --yes @trunkio/launcher check -a`** (Ruff, **Pyright**, Pylint, and security tools via Trunk).
+   - Re-run **`make dead-code`** until Vulture is clean or only acceptable leftover findings remain per project policy.
+   - For type-only triage, `uv run pyright` also reads `pyproject.toml` `[tool.pyright]`; prefer Trunk for CI parity.
+   - When the change affects **executable code** (behavior, types, imports beyond formatting), run **`make test`** after lint and Vulture pass (pytest-cov; see **Resources**). Same entrypoint as CI: `dev/test_python.sh`. Formatting- or comment-only edits may stop after `make lint` and **`make dead-code`**.
+   - If passed: Move to the next issue or finish if all are resolved.
+   - If failed: Analyze the new failure and repeat the loop.
+
+## Constraints
+
+- Do not silence Trunk/Ruff/Pyright/Pylint/Bandit/Semgrep findings with inline suppressions (for example `# noqa`, `# type: ignore`, `# pylint: disable`, `ruff: noqa`, file-level `# ruff: noqa`, or Trunk inline disable comments).
+- Do not broaden project configuration to hide violations (for example new `[tool.ruff.lint]` ignores, Pyright `report*` toggles, or Pylint disables) unless the user explicitly asked for that policy change.
+- Prefer **`make format`** / **`npx … fmt -a`** for auto-fixable style; otherwise fix the underlying issue the linter reports.
+- If fixes fail after genuine attempts, stop and surface the finding for a human to decide—do not add suppressions to make CI green.
+
+## Termination Criteria
+
+- No more errors reported by **`make lint`** (or equivalent **`npx … check -a`**).
+- **`make dead-code`** exits successfully (no unresolved dead-code issues per project expectations).
+- When fixes touched executable code: **`make test`** passes.
+- Reached max iteration limit (default: 5).
+
+## Examples
+
+### Scenario: Fixing a formatting violation
+
+1. `make lint` reports formatting issues in `src/your_package/main.py`.
+2. Agent runs `make format`.
+3. `make lint` and `make dead-code` now pass.
+
+### Scenario: `trunk` not on PATH
+
+1. `make lint` fails with “trunk: command not found”.
+2. Agent runs `make setup-tools` or `npx --yes @trunkio/launcher check -a` and continues the loop using `npx --yes @trunkio/launcher fmt -a` for formatting until checks pass.
+
+## Resources
+
+- [Trunk Documentation](https://docs.trunk.io/): Official documentation for the Trunk CLI.
+- [Install Trunk CLI (including NPM launcher)](https://github.com/trunk-io/docs/blob/main/code-quality/overview/cli/getting-started/install.md): Launcher behavior and `@trunkio/launcher`.
+- [pytest-cov](https://pytest-cov.readthedocs.io/) / [Coverage.py](https://coverage.readthedocs.io/): Test coverage used by `make test` / `make coverage`.