/maestro-audit

name: maestro-audit
version: 1.13.7
description: "Audit a project using Maestro read-only: use for code review, architecture review, deepening opportunities, backlog proposals, harness-improvement findings, or repo-wide improvement audits without fixes."

Maestro Audit

Use this for repo-wide improvement audits. The audit is agent work; Maestro only stores, merges, and surfaces proposals. Architecture reviews that write an HTML report use the OS temp directory only, not the repo.

Activate with a known session id: `maestro hook record --event skill_activation --skill maestro-audit --session <session_id>`

Recipe checkpoint: Maestro's main workflow is the loop. Use `maestro status` for current state and `maestro loop next` as the read-only router when the next recipe is not obvious. Audit work uses `maestro loop show audit`. Use that recipe as the shape for perceive -> choose -> act -> observe -> learn -> continue: read the bounded surface, choose a falsifiable probe, run read-only checks, observe findings, record durable proposals, then return the next audit or hard stop. Writes still use the existing Maestro verbs named by the recipe. Custom card/run recipes are allowed only when no shipped recipe fits, and must use the same six phases, current Maestro verbs, hard stops, and continue output. Rule: loop next recommends; outcome/proof/memory verbs write. Use `maestro loop next --chain` to explain current chain position without writing, `maestro loop outcome` to preserve structured attempt outcomes and transition receipts after native work, `maestro loop trace <card>` to audit card-scoped receipts, and `maestro loop improve` for read-only proposals over sourced outcomes. Audit may file explicit harness or memory proposals. Do not use silent recipe mutation, hidden stores, hidden schedulers, or proof/QA bypass.

Stop

Do not implement, edit code, or change repo artifacts during this skill run. Produce proposals only. Temp HTML architecture reports are allowed when the architecture-review branch asks for them. Audit findings are backlog-only during witness sign-off. File durable proposals with `maestro harness propose`; they do not become close blockers unless they invalidate the accepted contract, proof, QA, or risk-tier policy.

Do

1. Read known state: `maestro status`, `maestro harness list --all`, active features, active tasks, decisions, and repo instructions. Pick the bounded audit surface before proposing findings. 2. Map the bounded audit surface from repo evidence: docs, code ownership boundaries, tests, scripts, and shipped embedded resources relevant to the finding. Native harness layer audit route: run `maestro capability` when a finding or review depends on optional tools, files, connectors, or host receipts; run `maestro maturity` when the audit needs context, acceptance, proof gaps, UX friction, maturity level, or next-owner evidence. Generated CLI references prove command shape; Harness and targeted skills teach the workflow. Sweep every lens so coverage is checkable, not just whatever surfaced first: correctness, security, performance, test coverage, tech debt, dependencies, developer experience, docs. The tech-debt lens includes the reach-ladder (HARNESS Code style): code a lower rung -- stdlib, native platform, an installed dependency, a one-liner -- already covers. The session lean mode tunes how strictly to propose these (`maestro lean`): `ultra` proposes replacing such code, `full`/`lite` propose the cheaper form, `off` skips the reach-ladder lens. `maestro lean audit` runs the focused, mode-adjusted reach-ladder pass; this skill still only proposes (no edits, no markers). For architecture deepening opportunities, use [reference/architecture-review.md](reference/architecture-review.md). 3. Vet each finding before filing: try to refute it against the live repo (re-read the code, re-run the command). Drop findings that do not survive. 4. Cross-check findings against Maestro state so you do not propose work already accepted, dismissed, measured, or covered by active tasks. 5. Re-propose every finding still seen with `maestro harness propose` (signatures: [reference/cli.md](reference/cli.md)). Use one stable `--topic` per finding so the verb merges repeats, and end the `--evidence` text with a leverage estimate: `impact/effort/confidence: <H|M|L>/<H|M|L>/<H|M|L>`.

Completion criterion: every surviving finding has a `maestro harness propose` record with stable topic, concrete evidence, and leverage estimate; every finding that failed refutation or Maestro-state cross-check is dropped.

Evidence

Each proposal needs concrete evidence: file paths, line numbers, command output, or exact artifact names, plus the closing `impact/effort/confidence` estimate (`H`, `M`, or `L` each) so the backlog ranks without re-deriving it. Do not file style opinions without a repo-specific impact and a way to verify the improvement.

Hand-off

Pipeline: `[maestro-audit] -> maestro harness apply -> maestro-card` Architecture pipeline: `[maestro-audit: architecture report] -> maestro-design (deepening-candidate + grilling + domain-model) -> maestro-card`

Next: proposals filed -> inspect with `maestro harness list`; accepted proposals spawn normal tasks through `maestro harness apply <id>`.