Skip to content

SKILL.md

Latest commit

 

History

History
113 lines (83 loc) · 4.31 KB

SKILL.md

File metadata and controls

113 lines (83 loc) · 4.31 KB
Raw
name slopper
description Read-only repo-domain audit for finding docs-code drift, hidden existing behavior, plaster seams, bloated files, duplicate docs, and cleanup/refactor candidates before implementation.

Slopper

Slopper is a read-only findings skill. It gives the agent a search and reasoning frame for one bounded repo domain. It does not edit files, refactor code, update docs, run cleanup, or bless one truth silently.

Default output is a chat report. Write a file only when the user explicitly asks.

Hard Boundary

  • Do not mutate files.
  • Do not format, generate, migrate, refactor, archive, or patch.
  • Do not slide from audit into implementation.
  • Do not use the internet unless the user asks or repo docs/code point to external truth that is central to the mismatch.
  • End by asking whether the user wants a separate implementation/doc-cleanup pass for selected findings.

Audit Fit

Accept a path or concept domain, such as frontend auth, billing API, docs onboarding, workflow scripts, or market data adapter.

After a quick map, decide whether the requested domain is auditable in one pass. If not, say why and propose smaller slices. Do not use folder size alone; judge by domain shape, doc spread, and expected report reliability.

Workflow

  1. Map before searching broadly.

    • Read repo front doors, indexes, task maps, architecture maps, or domain README files if they exist.
    • Prefer repo-owned search helpers when documented.
    • Fall back to rg, find, and git only when maps are missing, stale, or insufficient.

  2. Read domain docs as claim sources.

    • Include task/status files when the repo has them.
    • Extract a compact Claims Tested list before judging code.
    • Claims can include: exists/missing, owner file/module, canonical API/seam, temporary fallback, active/queued/completed status, intended doctrine.

  3. Read current reality.

    • Inspect relevant code, tests, fixtures, and lightweight git context.
    • Tests are supporting evidence only. Do not run a test ladder by default.
    • Use recent commits or file history lightly when it explains drift.

  4. Compare claims against reality.

    • Default bias: code is often ahead of docs, but code is not automatically right.
    • If code clearly implements newer behavior, mark docs/tasks/index as likely stale.
    • If code contradicts explicit doctrine, mark code drift rather than updating docs to bless it.
    • If neither side is clearly authoritative, mark an unresolved truth conflict.

  5. Report findings only.

    • Rank by future-agent damage, not generic severity.
    • Include compact receipts for every finding.
    • Include confidence, blast radius, primary action, optional secondary actions, and obvious likely cause only when evidence supports it.

Finding Order

Use this order:

  1. Truth drift findings.
  2. Plaster vs fortress findings.
  3. Structure/cleanup candidates.
  4. Review agenda.

Include empty sections tersely, for example none found, so the user can see each axis was checked.

Finding Types

  • Docs lag code: code already implements behavior docs/tasks still call missing, old, or future.
  • Code drifted from doctrine: code violates current architecture/product/workflow doctrine.
  • Unresolved truth conflict: docs and code disagree and owner intent is unclear.
  • Missing exposure: code exists but repo maps, indexes, README files, or task truth do not expose it.
  • Doc overlap / ownership salad: multiple docs claim the same truth or point future sessions down competing paths.
  • Plaster vs fortress: current solution works as glue, fallback, hardcoded data, fixture, or one-off bridge where a real seam/API/contract/module boundary should exist.
  • Structure refactor signal: a bloated file/doc mixes responsibilities or is hard for future agents to reason about.

Report Template

Scope:
- ...

Maps Used:
- ...

Claims Tested:
- ...

Already Exists Receipts:
- ...

Truth Drift Findings:
- Finding:
  - Type:
  - Confidence:
  - Blast radius:
  - Receipts:
  - Likely cause: ... / Cause unclear
  - Primary action:
  - Secondary actions:

Plaster vs Fortress Findings:
- ...

Structure/Cleanup Candidates:
- ...

Review Agenda:
- Safe doc/index/task updates:
- Owner decisions needed:
- Later refactor candidates:

Stop Point:
- Findings only. Review these before any implementation/doc-cleanup pass.