# Product Audit

> >

- **Type:** Skill
- **Install:** `agentstack add skill-gtrabanco-agentic-workflow-product-audit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gtrabanco](https://agentstack.voostack.com/s/gtrabanco)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [gtrabanco](https://github.com/gtrabanco)
- **Source:** https://github.com/gtrabanco/agentic-workflow/tree/main/skills/product-audit

## Install

```sh
agentstack add skill-gtrabanco-agentic-workflow-product-audit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Product Audit

The **CTO health check**: run every few features, before a release, or when the
product is "done", to answer *"where do we actually stand, and what should we do
next?"* across the entire product. **Read-only and recommend-only — it never
fixes, opens issues, or edits the roadmap. It proposes; the human decides.**

## Turn contract — verify before ending the turn

```
✓ The full PRODUCT AUDIT report was printed in the fixed output format (health by dimension, ranked findings, three proposal streams)
✓ Nothing was fixed, filed, or changed — report only
✓ The closing `→ Next:` block is printed, then the machine envelope (fenced ```json — see ## Machine envelope) as the ABSOLUTE last output
```

About to end the turn with any box unchecked? The turn is NOT done — complete
the missing box first (weak models drop end-of-document duties; this list is
first on purpose).

## When to use

- Periodically (every few features) or at a product-ready milestone.
- When you want the broad, honest picture — quality, security, debt, docs, and
  roadmap — not the review of a single change (`review-change`) or PR (`audit-pr`).

This is the widest lens in the workflow. `review-change` audits a diff, `audit-pr`
a PR, `audit-docs` doc↔roadmap↔code coherence — `product-audit` audits the
**whole product across every dimension** and turns what it finds into proposals.

## Scope

The entire codebase and its process artifacts: source, tests, the docs tree, the
roadmap, the fix index, open issues, and every feature folder's planning docs.
Accept an optional path/area to focus a partial audit; state the scope and, if you
sample rather than exhaust a dimension, **say what you sampled** — never imply full
coverage you didn't do.

> **Tip (provisional).** For the broadest, deepest run, the *user* can turn on
> `ultracode` (`/effort ultracode` — a Claude Code session setting pairing xhigh
> effort with automatic multi-agent orchestration) so this sweep fans out across
> parallel subagents instead of one context window. It's a research-preview feature
> and a **session choice** — not something this skill declares (no skill can set
> `effort: ultracode`). On agents without it, run the audit as-is: sequential
> passes over each dimension — only wall-clock changes, never coverage.

## Step 0 — Discover the project (always first)

Per the agent guide's **Workflow conventions** + **documentation map**, then read
what THIS skill needs: the roadmap, the fix index, the feature folder layout, and
the verification gate. From the map decide the product's nature (web / mobile /
console / library / backend / infra) and which axes apply — the same applicability
logic `review-change` uses, applied product-wide. Note any optional platform
review skills the project installed (extras, never requirements — the internal
pack covers every axis).

## Audit dimensions (platform-adaptive — run only what applies)

| Dimension | What it sweeps product-wide | Applies to |
|---|---|---|
| **Correctness & architecture** | Bugs, layer/boundary violations, dead code, overengineering, drift from the architecture doc | all |
| **Security & cybersecurity** | Secrets in repo, authz gaps, input validation, dependency / supply-chain risk | all |
| **Performance** | Hotspots, complexity, N+1s, bundle/asset weight (web), resource leaks | all |
| **Tests** | Coverage of critical paths, missing/!flaky tests, untested failure modes | all |
| **UX / UI** | Design-system adherence, broken states, inconsistency | web / mobile / TUI |
| **Accessibility** | a11y conformance for user-facing surfaces | web / mobile |
| **SEO** | Indexability, metadata, structured data | web |
| **Brand / voice** | User-facing copy vs. the brand guide | surfaces with copy |
| **Tech debt** | Accumulated shortcuts, TODO/FIXME, stale abstractions | all |
| **Process & docs** | Incomplete phases, aging open issues, **solvable known-issues**, doc completeness, missing/optimizable workflow docs | all |
| **Workflow discipline** | The workflow's own rules held: branch/PR discipline, `done · #` links, phase naming (`P1…`), per-phase docs, commit format, dependency closures, artifact language — **run `audit-docs` checks 1–13 mechanically** (compose it); never assume a rule held because it "should" | all |
| **Roadmap coherence** | Stale/obsolete/superseded features, missing dependencies, gaps & opportunities | all |

Skip inapplicable axes (no a11y/SEO/brand for a CLI/library/infra product) and
**say which you skipped and why**. Every axis is covered by the workflow's own
internal review pack (`review-code`, `review-security`, `review-verify`,
`review-debt`, `review-design`, `review-a11y`, `review-brand`, `review-perf`,
`review-seo`) — installed with the workflow, so an applicable axis can never be
"missing". Platform skills the project installed run as optional extras on top.

## Process

1. **Map & decide axes** — Step 0; mark each dimension applicable / n-a.
2. **Sweep code & axes** — run the applicable axes across the codebase: compose
   `review-implementation` plus the internal review pack's applicable passes
   (each returns its fixed-format table + PASS|FAIL), and any optional installed
   extras. Classify findings (severity + fix-now / postpone / tradeoff).
3. **Audit process & docs** — incomplete phases (`progress.md`/`TASKS.md`), aging
   open issues, **solvable known-issues** (trigger now met), doc-map completeness
   (compose `audit-docs`), and missing/optimizable workflow docs.
4. **Mine accumulated suggestions** — read every feature folder's `decisions.md`,
   `known-issues.md`, and `architecture-notes.md`; extract deferred items, open
   questions, and recorded debt. Cluster duplicates across features.
5. **Synthesize proposals** — turn findings + mined items into three concrete,
   deduped, severity-ranked streams:
   - **Issues to open** — bugs, debt, security/perf items worth tracking.
   - **Roadmap: add** — features/capabilities the evidence now justifies.
   - **Roadmap: remove or revise** — features that are obsolete, superseded, or no
     longer make sense.
6. **Report** — the format below. Recommend; do not act.

## Output format

```
PRODUCT AUDIT —  (scope: )
Coverage: 

Health by dimension:
   .......... ✓ healthy | ⚠ concerns | ✗ at risk | n-a (why)
  ...

Top findings (severity-ranked):
  [SEV]  —  — evidence:  — class: 
  ...

Proposals — the user decides which to act on:

  Issues to open:
    -  [sev] —  — route: triage-issue / plan-fix — evidence: 
  Roadmap — add:
    -  —  — route: plan-feature
  Roadmap — remove / revise:
    -  —  — route: triage-issue / roadmap edit

Manual-verification checklist (what automation can't confirm):
  -  …

→ Next: /triage-issue  — classify them in one batch
  · accepted bug/debt → /plan-fix   · accepted capability → /plan-feature
  · nothing to act on → record the verdict and move on
```

Lead with the honest one-line health verdict (e.g. "shippable with 2 high-sev
security items to track first").

## Guardrails

- **Never auto-fixes, never opens issues, never edits the roadmap.** Output is a
  report + proposals; **every action is the user's decision.** When the user
  accepts, route: `triage-issue` files/classifies, `plan-feature` adds roadmap
  work, `plan-fix` scopes a concrete fix.
- Platform-adaptive: run only applicable axes; always list what you skipped and why.
- **No silent caps.** If you sampled, prioritized, or time-boxed a dimension, say
  so — never present partial coverage as exhaustive.
- Severity-ranked and deduped: cluster the same issue found via multiple axes or
  multiple feature docs into one proposal.
- Honor the project's **Workflow conventions** (docs-language, evidence): every
  finding/proposal cites a `file:line`/metric/doc/issue source; mark uncertainties *verify*.

## Machine envelope

Every invocation ends with the **machine envelope** — schema, field rules and
placement per the installed `orchestration-envelope` skill: one fenced
```json block, printed **after** the closing block above, as the **absolute
last output** of the turn (external orchestrators parse the LAST fenced json
block; see `docs/workflow/ORCHESTRATION.md`). All top-level keys always
present; values only from verified command output, never invented.

This skill emits:

- **`state`:** `OK` (report delivered — proposals await the human) or `HALT`
  (a critical finding that must stop all in-flight work — scope `run`).
- **Fields:** `findings` aggregates the report (fix_now = critical items;
  untriaged = proposals not yet accepted); `recommendations.product_audit:
  false` (it just ran) with `reason` = the suggested next cadence.
- `detail`: `{"proposed_issues": [...], "proposed_features": [...], "axes": {"": "PASS|FAIL|n/a"}}`.

## Portability (agents other than Claude Code)

The workflow is the contract; Claude Code features are conveniences. On an
agent that lacks one, apply the fallback — never skip the step the feature
enables:

- **No slash-command menu** — where this skill says `/`, open that
  skill's `SKILL.md` (wherever your agent installed the skills) and follow it
  literally, in a fresh conversation: hand-offs assume a clean context.
- **No per-skill `model:`/`effort:`** — this is the widest, highest-stakes
  sweep in the workflow: run it on your **strongest** model at its deepest
  setting, as its own dedicated run — never squeezed into another task's
  context.
- **No `ultracode`/subagents** — sweep the dimensions sequentially (see the
  tip above); state coverage honestly either way.

## Relationship to other skills

```
product-audit (whole product, all axes, periodic)
   ├─ composes review-change axes (codebase-wide) + audit-docs (doc coherence)
   ├─ mines feature docs (decisions / known-issues / architecture-notes)
   └─ proposes ─┬─ Issues to open ........ ▶ triage-issue / plan-fix
                ├─ Roadmap: add .......... ▶ plan-feature
                └─ Roadmap: remove/revise  ▶ triage-issue / roadmap edit   (user decides)
```

- Broader than `review-change` (one change) and `audit-pr` (one PR); subsumes
  `audit-docs`'s coherence check as one of its dimensions.
- Hands nothing off automatically — it recommends, and the planning/fix/triage
  skills execute only when the user chooses to.

## Done when

- Every applicable dimension has a health verdict backed by cited evidence, and the
  skipped or sampled ones are stated.
- A severity-ranked findings list plus three proposal streams (issues to open,
  roadmap add, roadmap remove/revise) exist, deduped and each routed.
- Nothing was fixed, filed, or changed — the report is the deliverable; the user
  decides what to act on.
- The **closing `→ Next:` block is printed** — typically a batch `/triage-issue` for
  the proposed issues, then `/plan-feature` / `/plan-fix` for the accepted work.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gtrabanco](https://github.com/gtrabanco)
- **Source:** [gtrabanco/agentic-workflow](https://github.com/gtrabanco/agentic-workflow)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-gtrabanco-agentic-workflow-product-audit
- Seller: https://agentstack.voostack.com/s/gtrabanco
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.