# Repo Bug Finder:package

> Use when repo-bug-finder discovery is complete and the user asks to package confirmed or probable findings into final Bug records, indexes, handoff materials, or an HTML report.

- Skill: `aiden0z/repo-bug-finder-package` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add aiden0z/repo-bug-finder-package`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aiden0z/repo-bug-finder-package/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: aiden0z (https://skillmd.com/u/aiden0z)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/aiden0z/repo-bug-finder-package

---


# Repo Bug Finder: Package

## Purpose

Convert discovery readiness into a final handoff package. This subskill is packaging-only: it must not read new code facts, hunt for new Bugs, or promote scanner hits that were not triaged during discovery.

## Boundary

Input:

- `work/discovery-readiness.json`
- `work/discovery-readiness.md`
- `work/architecture-signals.json` and `.md` when present
- triage/source-pack references produced during discovery
- user-approved scope and language

Output uses this standard package structure:

```text
submit/
  README.md
  bug-audit-report.html
  findings/P1/
  findings/P2/
  findings/P3/
  findings/P4/
  indexes/
  knowledge/
  quality/
  standards/
```

## Workflow

1. Read `references/packaging-workflow.md`, `references/package-output.md`, `references/bug-schema.md`, `references/risk-taxonomy.md`, and `references/interactive-html-report.md`.
2. Export discovery readiness into the package structure:

   ```bash
   python3 scripts/export_readiness_to_package.py <workspace> --project <name> --language zh
   ```

   `--workspace <workspace>` is accepted as an agent-friendly alias for the positional workspace.

3. Convert only clean package-ready records into Bug Markdown files. When readiness provides `summary.clean_package_ready_record_ids`, export only those records; otherwise fall back to eligible confirmed/probable records from older readiness files.
4. Assign continuous IDs starting at `BUG-0001` with no gaps.
   Sort before assigning IDs: `confidence` high -> medium -> low, then priority P1 -> P2 -> P3 -> P4.
5. Put probable records in the final package only when the sole missing gate is `trigger-path`; label `confidence: medium` or `low` and state the trigger as a hypothesis.
6. Keep `candidate`, `refuted`, and `merged` records in candidate/quality coverage, not as final Bugs.
7. Generate indexes:

   ```bash
   python3 scripts/generate_bug_index.py <workspace>/submit
   python3 scripts/generate_candidate_index.py <workspace>/submit
   ```

   Package scripts that operate on `submit/` also accept `--submit-root <workspace>/submit` or `--workspace <workspace>`.

8. Run pre-package validation before HTML generation when final HTML is expected:

   ```bash
   python3 scripts/validate_bug_package.py <workspace>/submit
   ```

   Do not pass `--repo-root` by default. In this workflow, `work/discovery-readiness.json` is the package source of truth. Use `--repo-root` only when the user explicitly asks for source-path existence validation against local checkouts.

9. Generate the HTML report:

   ```bash
   python3 scripts/generate_bug_report_html.py <workspace>/submit --language zh
   ```

10. Run final validation:

   ```bash
   python3 scripts/validate_bug_package.py <workspace>/submit --require-html-report
   ```

Use `--language en` and English Bug headings only when the final deliverable is English.

## ⛔ BLOCKING GATES

- No new code reading in packaging.
- No new Bug facts in packaging.
- No architecture findings invented during packaging; architecture review must come from readiness records or `work/architecture-signals.json`.
- No dependence on untriaged pattern or scanner artifacts during packaging.
- No non-contiguous Bug IDs.
- No candidate-only records in `submit/findings/`.
- No records blocked by unknown/missing source packs or schema/package-blocking debt in `submit/findings/` when readiness exposes clean package-ready IDs.
- No HTML report before indexes and validation receipts required by the generator are satisfied.
- No final handoff claim until validation passes.

## Evidence Contract

Final package completion must produce:

- `submit/findings/P*/BUG-*.md` for promoted confirmed/probable records.
- `submit/indexes/findings.generated.json` and `submit/indexes/candidates.generated.json`.
- `work/package-validation/prepackage-validation.passed.json` before HTML generation.
- `submit/bug-audit-report.html` when a final report is requested.
- final `validate_bug_package.py <workspace>/submit --require-html-report` output when HTML is generated.

## Output Contract

The package structure, Bug schema, index format, and HTML report style are part of this subskill's own contract. Keep them stable for downstream readers.