Przejdź do treści
Biblioteka skilli
Programowanie · Przegląd i audyt

codebase-health

/codebase-health

Prowadzi audyt zdrowia kodu obejmujący martwy kod, pakiety, sekrety, nieaktualne dokumenty i duplikaty.

Repozytorium
paqad-ai ↗
Licencja
MIT
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

90/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść25 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Prowadzi audyt zdrowia kodu obejmujący martwy kod, pakiety, sekrety, nieaktualne dokumenty i duplikaty.

Oryginalny opis (EN)

Runs the codebase health audit through the paqad-ai health verbs, then triages and narrates the findings on dead code, packages, secrets, stale docs and copy-paste, and retests an earlier report. Use when the user asks to check project or code health, audit the codebase, find dead code or unused code or packages, run a cleanup audit, or retest health findings; the workflow is codebase-health or health-retest.

Jak działa

  1. What It Does
  2. Use This When
  3. Inputs
  4. Procedure
  5. Output Contract
  6. Escalate / Stop Conditions
  7. Resources
Sekcje z nagłówków SKILL.md, w oryginale · 142 linii, 982 słów
Podgląd SKILL.md
---
name: codebase-health
description: Runs the codebase health audit through the paqad-ai health verbs, then triages and narrates the findings on dead code, packages, secrets, stale docs and copy-paste, and retests an earlier report. Use when the user asks to check project or code health, audit the codebase, find dead code or unused code or packages, run a cleanup audit, or retest health findings; the workflow is codebase-health or health-retest.
metadata:
  model_tier: reasoning
  cacheable: 'false'
  output_format: markdown
  paqad-meta: skill.meta.yaml
---

## What It Does

Audit the project for code and packages that no longer earn their place: dead code,
unused packages, outdated or risky packages, leaked secrets, stale docs, and copy-paste
AI slop. A sibling of pentest and design-test: same tier, routed and rule-driven, no
stage-gating. Detection is deterministic and costs zero model tokens; you orchestrate,
triage, and narrate.

A retest of an earlier report is the Retest mode of this skill.

## Use This When

Run this workflow whenever the user says anything equivalent to:

- "check my project's health", "codebase health", "code health", "health check", "health audit"
- "audit my codebase", "find dead code", "check for unused code/packages", "cleanup audit"

Do **not** improvise a health audit. Always follow the steps below in order. For a retest
of an existing report, use the `health-retest` workflow instead. Note: a security review
is **pentest**, not this workflow.

Use the Retest mode below when the workflow is `health-retest`.

## Inputs

### Source-of-Truth Model

There is one source of truth: the deterministic `paqad-ai health run` verb. It does all
detection and writes the findings JSON. You never re-derive or invent a finding: you run
the verb, read its output, triage it, and write the prose the report needs.

| Source                                                      | Role                                         |
| ----------------------------------------------------------- | -------------------------------------------- |
| `paqad-ai health run` output (`docs/health/<ts>.json`)      | **the findings**: proof is machine-generated |
| The code-knowledge index, dependency inventory, tool output | **primary evidence** the verb cites          |
| The human report `docs/health/<ts>.md`                      | **the deliverable** you narrate              |

## Procedure

Progress and outputs live under `.paqad/health/runs/<run_id>/` and `docs/health/`. The run
is resumable and baseline-ratcheted: the first run records `.paqad/health/baseline.json`,
and later runs mark each finding `new-since-baseline` vs `pre-existing`.

### Step 1: run the verb

Run `paqad-ai health run` (add `--offline` if the user asked to skip network checks). It:

- reuses the code-knowledge index for dead code + unused dependencies (run `paqad-ai index
build` first if it reports `blocked_checks: index-not-built`),
- shells out to `osv-scanner`, `gitleaks`, `jscpd` when they are on PATH and degrades to a
  labelled fallback or a `blocked_checks` entry (with an install hint) when they are not,
- writes `docs/health/<ts>.md` + `docs/health/<ts>.json` and the per-run finding index.

The verb's exit code is the verdict: 0 clean, 1 findings, 2 an unexpected error.

### Step 2: read the findings JSON

Read `docs/health/<ts>.json`. Each finding carries `evidence[]` (the proof), a plain-words
`description` (why it matters), a `suggestion` (remove / update / reuse / rotate / rewrite),
a `tier` (`deterministic` or `ai-judged`), and a stable `HL-` id. Never restate a finding
the verb did not produce, and never expose a secret's bytes: secret findings carry only a
file:line + rule + fingerprint.

### Step 3: triage

Sort the findings into the four-pile triage ledger (`.paqad/findings/triage.json`): confirmed,
unclear-spec, false-alarm, taste. Deterministic findings are proof-backed; `ai-judged`
candidates (stale-doc, ai-slop) are yours to grade: accept, downgrade, or dismiss with a
one-line reason. Deletion and rewrites are always a human decision; when the user wants to
act, route irreversible removals through the Decision Pause Contract.

### Step 4: narrate the report

Speak in the paqad voice. Lead with the honest split the report already draws: **Proven**
findings (mechanically proven) and **Needs judgment** findings (candidates you graded).
Give the user the verdict in the contract words (Safe to merge / Needs your attention /
Inconclusive), the top remediation priorities, and the blocked checks with their install
hints. Do not inflate confidence: a blocked check is a gap, not a pass.

### Retest mode

Use this mode for the `health-retest` workflow.

Re-run a prior codebase-health report and check off what got fixed. The retest never
invents findings and never lowers severity: it re-runs the same deterministic evidence and
reclassifies each source finding by its stable `HL-` id.

Run this workflow whenever the user says anything equivalent to:

- "health retest", "re-run the health check", "did my health findings get fixed?"

For a fresh audit, use the `codebase-health` workflow instead.

#### Inputs

- The source report sidecar. By default the newest `docs/health/*.json`; the user may name a
  specific one.

#### Step 1: run the verb

Run `paqad-ai health retest` (optionally `--sidecar <path>` to pick a specific source report,
`--offline` to skip network checks). It reads the source sidecar, re-runs the evidence, and
reclassifies each finding.

#### Step 2: read the retest JSON

Each source finding is now `fixed`, `still-open`, or `needs-manual-verification`, matched by
its `HL-` id. A network-required finding that could not be re-checked offline is
`needs-manual-verification`, not silently fixed.

#### Step 3: narrate the result

Report, in the paqad voice: how many are fixed, how many are still open, and how many need a
manual check. The verdict is Safe to merge only when nothing is still open. The retest report
is written to `docs/health/<orig-ts>-retest-<ts>.{md,json}`.

Retest mode rules:

- Never invent a new finding in a retest, and never lower a finding's severity.
- Match by stable `HL-` id, not by category.
- A network-required finding you could not re-check is `needs-manual-verification`, never `fixed`.

## Output Contract

- A health run writes `docs/health/<ts>.md` and the `docs/health/<ts>.json` sidecar, with stable `HL-` finding ids, and the per-run finding index under `.paqad/health/runs/<run_id>/`.
- A retest writes `docs/health/<orig-ts>-retest-<ts>.{md,json}` and keeps the source `HL-` ids.

## Escalate / Stop Conditions

- Never skip the verb. The findings come from `paqad-ai health run`, never from your own reading.
- If a scanner is unavailable, it is already recorded in `blocked_checks`: surface it, do not work around it.
- Secret evidence never contains the secret bytes. Only file:line + rule + fingerprint.
- Deletion, dependency removal, and rewrites are suggestions. Acting on them is the user's call.
- Always keep both the `.md` report and the `.json` sidecar; `health-retest` depends on the sidecar to preserve `HL-` ids.

## Resources

- Helper skill: `finding-normalizer`.
- `references/health-verbs.md`: read it when you need to see which verb a mode runs.
- `agents/openai.yaml`
Pliki w paczce (4)
  • SKILL.md 7 KB
  • skill.meta.yaml 1 KB
  • agents/openai.yaml 1 KB
  • references/health-verbs.md 1 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · eliyce/paqad-ai90MIT
paperwingio/paperwing90Apache-2.0

Migawka bazy z 13.11.2026 · wersja paczki 230c49f94e58 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100scan-codebase-health
    Wykrywa problemy zdrowia bazy kodu: nieużywane eksporty, rozjazdy liczb w dokumentacji, pliki osierocone i nieaktualne odwołania do konfiguracji.
  • 100scan-codebase-health
    Wykrywa problemy zdrowia bazy kodu: nieużywane eksporty, rozjazdy liczb w dokumentacji, pliki osierocone i nieaktualne odwołania do konfiguracji.
  • 90codebase-review
    Ocenia kondycję i utrzymywalność istniejącego kodu w dowolnym języku, zwracając uporządkowaną listę ustaleń.
  • 100run-ts-cleanup
    Porządkuje bazę kodu TypeScript: usuwa martwy kod, nieużywane zależności, bezwartościowy kod z generatorów AI i słabe typy.
  • 100audit
    Audytuje repozytorium lub pakiet jednorazowo: błędy, bezpieczeństwo, obciążenie, ryzykowny kod i martwy kod, bez zmian w kodzie.
  • 100code-health-audit
    Audytuje jakość, wydajność i koszt działania istniejącego kodu, wskazując martwy kod, wolne zapytania i nadmiar logów.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.