audit
Audit pipeline artifacts for gaps, inconsistencies, missing coverage and staleness: one document, cross-stage traceability across .gener8v/, or a ticket or externally-authored plan reconciled against the real codebase (Go / Blocked), then resolve the findings interactively. Use when asked to 'check the spec for gaps', 'sanity-check this plan before we build it' or 'does this ticket still match the code', before committing to a stage, or at milestones. Audits documents and plans, not code: for delivered code use code-review, quality-review or security-review.
- License 许可
- MIT
- 最近更新
- 2026-10-22
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- audit
- effort
- xhigh
- description
- Audit pipeline artifacts for gaps, inconsistencies, missing coverage and staleness: one document, cross-stage traceability across .gener8v/, or a ticket or externally-authored plan reconciled against the real codebase (Go / Blocked), then resolve the findings interactively. Use when asked to 'check the spec for gaps', 'sanity-check this plan before we build it' or 'does this ticket still match the code', before committing to a stage, or at milestones. Audits documents and plans, not code: for delivered code use code-review, quality-review or security-review.
- argument-hint
- [pipeline | stage slug | reconcile ticket-or-plan]
02 资源文件 4
- 资产文件assets/audit-report.md2.3 KB
- 参考文档references/checks.md22.1 KB
- 参考文档references/example.md7.1 KB
- 其他SKILL.md.tmpl22.3 KB
03 SKILL.md 正文
Audit Skill
Purpose
Review pipeline artifacts for gaps, inconsistencies, missing coverage, and unresolved ambiguity — then work interactively with the user to resolve them. This skill acts as quality control across the entire pipeline. It can audit a single document in isolation or trace completeness across multiple stages. The goal is to catch problems before they compound downstream.
When to Use
Use this skill when:
- A pipeline stage has been completed and needs review before proceeding
- Multiple stages have been completed and cross-stage consistency needs verification
- The user wants a second pass on a PRD, specification, or ticket breakdown before committing to it
- Open questions have accumulated across documents and need triage
- The team suspects something was missed but isn't sure where
- A ticket (or an externally-authored plan) is about to be delivered and its assumptions about the codebase need verification against ground truth before any code is written
Input
Source: One or more pipeline artifacts from .gener8v/
Read from:
- Pipeline State:
.gener8v/pipeline-state.yaml(for quick status overview before deep audit) - PRD:
.gener8v/prd.md - System Context:
.gener8v/context.md - Specifications:
.gener8v/specifications/*.md - Constraints:
.gener8v/constraints/*.md - Dependency Map:
.gener8v/dependencies/dependency-map.md - Technical Design:
.gener8v/technical-design/*.md - Change briefs:
.gener8v/changes/*/change.md - Tickets:
.gener8v/changes/*/tickets/*/TICKET-*.md— one ticket, one file — plus each directory'sbacklog.md(overview, dependency chain, suggested ordering) - Delivery Records:
.gener8v/changes/*/delivery/*.md - Code Reviews:
.gener8v/changes/*/reviews/*-code-review.md - Quality Reviews:
.gener8v/changes/*/reviews/*-quality-review.md - Security Reviews:
.gener8v/changes/*/reviews/*-security-review.md - Legacy layout: a project whose
tickets/,delivery/andreviews/*-review.mdstill sit at the top level of.gener8v/is read as the pseudo-changeinitial— audit it as one change and recommend the one-time migration fromCONVENTIONS.md§2. Legacy ticket shape: a per-area ticket file (tickets/<area-slug>.mdholding### TICKET-NNN:sections) is still read — audit it as the breakdown it is and recommendgener8v-state.py split-tickets - Assessments:
.gener8v/reviews/*-owasp-top10-assessment.md,*-owasp-llm-top10-assessment.md,*-architecture-assessment.md - Flow maps:
.gener8v/flows/*.md; Sweeps:.gener8v/sweeps/*-sweep.md; Brownfield checkpoints:.gener8v/brownfield/*.md - Prior audits:
.gener8v/audits/*.md(to carry deferred findings forward rather than re-raise them) - Conventions:
.gener8v/CONVENTIONS.md— the vocabularies and rules the checks inreferences/checks.mdenforce scripts/gener8v-state.py lintoutput (plugin install) — prefix collisions, uncovered requirements and NFRs, missing ticket sections, missing@specannotations, dangling referencesscripts/gener8v-state.py metricsoutput (plugin install) — rework rate, verification pass rate, deferred reviews, approvals pending; cite these as evidence for Warnings, never author them- Delivered code files (for
@specannotation verification)
Expects: At least one artifact to exist. The skill adapts its checks based on what's available — auditing a PRD alone is valid, but auditing tickets without a specification is less useful and the skill will flag this.
Output
Produces: An audit report with findings, plus interactive resolution of issues with the user
Write to: .gener8v/audits/[scope]-audit-YYYY-MM-DD.md
Creates directory: .gener8v/audits/ if it does not exist
Naming convention:
- Single-document audit:
[stage]-[slug]-audit-YYYY-MM-DD.md(e.g.,specification-search-and-retrieval-audit-2026-08-26.md) - Cross-pipeline audit:
pipeline-audit-YYYY-MM-DD.md
Audits are never overwritten: each run writes a new dated file and its Summary states which earlier findings (by FIND-XXX and file) were still open, now resolved, or newly raised.
After interactive resolution, the skill updates the source artifacts directly. The audit report captures what was found and what was changed.
Audit Modes
Single-Document Audit
Review one artifact in isolation for internal quality.
Trigger: User points to a specific file or stage Scope: One document only
Cross-Stage Audit
Trace consistency and coverage across multiple pipeline stages.
Trigger: User asks to audit the pipeline, or multiple stages have been completed
Scope: All available artifacts in .gener8v/, including every change under changes/
Reconciliation Audit (artifact vs. reality)
Verify that an artifact's claims about the codebase are actually true — not whether the artifacts agree with each other (that is Cross-Stage), but whether they agree with the repository. This catches the failure the other modes can't: a perfectly self-consistent plan built on a false premise ("builds on existing schema," "table X exists," "script Y runs the checks").
Trigger: A ticket or externally-authored plan is about to be delivered; or the user asks whether a plan is actually executable against the current code Scope: One or more tickets or plans + the live codebase (schema, migrations, scripts, source files, referenced documents) Output verdict: Go (assumptions hold) or Blocked (named assumptions are false, with what must exist first)
Output Format
Write the report in the shape of assets/audit-report.md. Read it before writing the report and keep its headings: the next audit reads the ## Resolution Log to carry deferred findings forward, and gener8v-state.py counts the files under .gener8v/audits/ to decide the pipeline stage.
Checks
The full check lists live in references/checks.md — open it at Process step 3 and apply every group that matches the artifacts in scope. The groups:
Single-document (one group per artifact kind)
- PRD — structure, directional goals, 3–7 areas, no technology leakage, Status/Approved-by
- Change brief — header fields and Slug, the seven sections, Affected Capability Areas table, non-empty Must cut, declared Status vs derived
- Specification — atomic and testable requirements, unique prefix, NFR section with measurable targets and a verification method, change and amended tags, Status/Approved-by,
@spec Coverage - Constraints — rationale and impact, categories, interactions, no requirements (or NFR targets) masquerading as constraints, Architect approval
- Dependencies — direction/type/nature, no cycles, graph matches prose, critical path, shared resources
- Technical Design — AD-XXX completeness, requirement and NFR citations, constraint compliance, repository named per component in a workspace, Architect approval
- Tickets — one
TICKET-NNN.mdper ticket with the three header lines,backlog.mdpresent, no ticket living only as a heading in another file; scope matches the brief, Priority and Value present, Prior Art/Output root-relative, Known Hazards, acceptance criteria and NFR verification,backlog.mdBacklog Summary Priority column, ordering respects priority - Delivery Record — acceptance criteria, Files Produced exist and are root-relative, plan approved by Engineer, repository and verify commands,
@spec, Status/Verification vocabularies, Pre-Flight, Verification Run with NFR checks, Post-Review Amendments - Code Review — acceptance and requirement (incl. NFR) coverage,
@speccoverage, finding traceability, verdict vocabulary, deferrals matched by Known Hazards - Quality Review — all five categories rated, Test Coverage cites commands, verdict vocabulary
- Security Review — four categories, attack scenarios, OWASP 2025, CC-XXX violations Critical, Risk accepted by Security, Accepted Risks counted
- Assessments — every category or thesis assessed, qualified references, tickets named for code changes
- Flow Map — validator exits 0, edges and nodes complete, Unknowns honest, prose matches diagram
- Defect Sweep — Scope, proof per DS-XXX, Swept and clean, fix-now findings mapped to tickets
Cross-stage
- Coverage — area → spec → constraints → design; brief areas → ticket breakdowns
- Change Traceability — every change has a brief, brief Requirements column matches the spec's change tags, ticket scope follows the brief, qualified references carry the change segment, legacy layout flagged
- Approvals — Warning (never a block) when tickets came from a Draft specification or delivery started under a Draft change brief; approval lines name a role and date
- Traceability — every REQ and NFR in a ticket, unique prefixes, constraint/dependency/AD references exist, Prior Art points at declared Output
- Delivery Traceability — records per ticket under the same change, Files Produced vs Output, predecessors delivered first, qualified DEL/CR/QR/SEC references,
@specin code - Review Traceability — three reviews or an explicit deferral, criteria match, CC-XXX references exist, verdicts agree with
pipeline-state.yaml, deferred findings become Known Hazards - Root-Relative Paths — every code path in every artifact is workspace-root-relative and, in a workspace, starts with a repository from
context.md - Consistency — open questions not duplicated, resolved upstream, no orphans (standalone artifacts are not orphans)
- Staleness — downstream documents reference current upstream IDs, IDs append-only, amended requirements flagged for re-review
Ground-truth reconciliation (Reconciliation Audit)
- Schema & Data Model · Files, Scripts & Commands · Referenced Documents · Decision Closure — artifacts vs the actual codebase; each failure is at least a Gap, Critical if it blocks delivery
Severity Levels
- Critical: Blocks downstream work or produces incorrect output. Must be resolved before proceeding. Examples: missing capability area with no specification, circular dependency, requirement with no ticket coverage.
- Gap: Something is missing that should be present but doesn't block immediate progress. Should be resolved before implementation. Examples: empty edge cases table, missing constraints analysis for a specification, open question that affects ticket scope.
- Warning: Potential issue that may cause problems later. Worth reviewing but can proceed. Examples: subjective language in a requirement, a Large ticket that might benefit from splitting, a soft dependency not reflected in sequencing.
- Suggestion: Improvement opportunity. Non-blocking. Examples: reworded requirement for clarity, additional user scenario, constraint that could be more specific.
Process
-
Determine Scope: Identify which artifacts exist in
.gener8v/and whether this is a single-document, cross-stage, or reconciliation audit. A reconciliation audit also needs access to the live codebase, not just.gener8v/. -
Read Artifacts: Load all in-scope documents and
CONVENTIONS.md. Note which expected artifacts are missing. Read prior audits so deferred findings are carried forward, not re-raised. Runpython3 ${CLAUDE_PLUGIN_ROOT}/scripts/gener8v-state.py lintand treat each line as a candidate finding; for a cross-stage audit also run… metricsand keep the numbers as evidence for Warnings. When the script is unavailable, run the same checks by hand fromreferences/checks.md. After resolving findings that change artifacts, re-runlintto confirm they clear. For a reconciliation audit, also read the codebase ground truth the artifacts reference — schema/migrations, scripts, and the cited documents. -
Run Checks: Open
references/checks.mdand apply every group that matches the artifacts in scope. For cross-stage audits, run single-document checks first, then cross-stage checks — including the Change Traceability and Approvals groups for every change underchanges/. For reconciliation audits, run the Ground-Truth Reconciliation checks against the codebase and produce a Go / Blocked verdict. -
Draft Findings: For each failed check, create a finding with severity, location, description, impact, and recommendation.
-
Present to User: Share the findings with the user, starting with Critical items. For each finding:
- Explain the issue clearly
- Propose a specific fix
- Ask the user to approve, modify, or defer
-
Resolve Interactively: Work through findings with the user:
- Approve: Apply the recommended change to the source artifact
- Modify: User provides direction; apply their preferred fix
- Defer: Mark the finding as deferred with a note on why
- Dismiss: User determines this is not an issue; mark as dismissed with rationale
-
Update Source Artifacts: Apply approved changes directly to the
.gener8v/files. Do not create separate "fixed" copies. -
Write Audit Report: Write the report as soon as findings are drafted (step 4), every finding
Open, and update each finding's Status and Resolution Log row as it is decided in steps 5–7 — a session that ends mid-audit loses nothing. The dated file name means the previous audit's Resolution Log is never overwritten. -
Summarize: Present a final summary — what was found, what was resolved, what remains open.
Example
A cross-pipeline audit of the Support Documentation Search System with one change (support-search): a missing specification, a subjective requirement, a Draft-specification Warning, the per-change coverage view and the Resolution Log. See references/example.md. Read it before producing your first artifact of this kind.
Troubleshooting
- The state script is unavailable. Under a copied install
${CLAUDE_PLUGIN_ROOT}is not substituted, so the command fails with No such file; withoutpython3it fails outright. Run the matching groups fromreferences/checks.mdby hand, and cite no metric: numbers in an audit come fromgener8v-state.py metrics, never from the model's own counting. - The project has no
.gener8v/. There is nothing to audit, and this skill never generates the missing artifacts. Recommend Setup, then Planning (no source yet) or Brownfield (existing code). - The
lintoutput ends with(exit 1). Lint exits 1 whenever it prints anERROR; its output is still complete. EachERRORis a candidate finding whose severity is decided by the Severity Levels, not by the lint label. - A reconciliation audit cannot reach the code. The artifacts sit in
.gener8v/but the repository they describe — or one repository of a workspace — is not in the working tree. Do not return Go on assumptions nobody verified: record each one as a Gap and ask for access (/add-dir, or run from the workspace root). - A finding still appears in
lintafter its fix was applied. The fix went to a file the script no longer reads — most often a legacy per-areatickets/<area-slug>.mdbeside atickets/<area-slug>/directory, which the script ignores once the directory exists. Apply the fix to the ticket file, then re-runlint. - The session ended mid-resolution. The report was written before the first finding was discussed (step 8). Resume from it: findings still
Openare the ones left, and the Resolution Log holds every decision already made.
Integration with Other Skills
Upstream (audits output from):
- Planning Skill: Audits PRD for structure, completeness, and technical leakage; audits change briefs for format, priority cut, and requirement deltas that match the specification's change tags
- Specification Skill: Audits specifications for atomicity, testability, namespacing, NFR verifiability, change tags, and traceability
- Constraints Skill: Audits constraints for categorization, rationale, and impact mapping
- Dependencies Skill: Audits dependency maps for completeness, circularity, and sequencing validity
- Technical Design Skill: Audits architecture decisions for completeness, constraint compliance, and requirement traceability
- Ticket Breakdown Skill: Audits tickets for coverage of the change brief's scope, Priority and Value, Prior Art/Output completeness, and acceptance criteria quality
- Delivery Skill: Audits delivery records for acceptance criteria verification, file existence, plan approval, decision documentation, and deviation tracking
- Code Review Skill: Audits code reviews for traceability completeness, finding quality, and verdict consistency
- Quality Review Skill: Audits quality reviews for assessment completeness and finding quality
- Security Review Skill: Audits security reviews for OWASP compliance, attack scenario presence, risk acceptance documentation, and compliance constraint coverage
Downstream:
- This skill modifies source artifacts directly during interactive resolution
- Audit reports are reference documents; no other skill consumes them as input
Principles
Write First, Resolve Second
The report exists before the first finding is discussed. Decisions the user makes are written into the file as they are made, not remembered until the end.
Interactive, Not Automated
This skill does not silently fix problems. Every finding is presented to the user with a recommendation. The user decides: approve, modify, defer, or dismiss. The skill is a partner in quality, not an autonomous corrector.
Start with Critical, End with Suggestions
Present findings in severity order. Critical issues must be addressed before the pipeline can proceed reliably. Suggestions are opportunities, not obligations.
Trace Across Stages
The highest-value checks are cross-stage: does every requirement have a ticket? Does every ticket's Prior Art point to real output from a real predecessor? Single-document quality matters, but pipeline consistency is where gaps hide.
Fix in Place
When the user approves a fix, update the source artifact. Do not create parallel "fixed" or "v2" copies. The pipeline should always have one source of truth per artifact.
Audit Reports Are Records, Not Artifacts
The audit report documents what was found and decided. It is not consumed by downstream skills. It exists for the user's reference and for traceability of decisions.
Revisions
- Audit reports capture a point-in-time assessment — they do not auto-update when source artifacts change
- After significant pipeline changes, re-run the audit to get a current assessment
- Previous audit reports remain in
.gener8v/audits/for reference; file names carry the date so nothing is ever overwritten - The Orchestrate skill tracks completeness (what exists); the Audit skill tracks quality (is it good) — they are complementary
Notes
- This skill can be run at any point in the pipeline — it adapts to whatever artifacts exist
- Running a cross-stage audit with only a PRD produces limited findings (mostly "missing specification" gaps); this is expected and useful for planning next steps
- The skill does not generate missing artifacts — it identifies what's missing and recommends which skill to run
- Multiple audit reports coexist in
.gener8v/audits/, dated in the file name; the newest states which earlier findings are still open - If the user has resolved open questions during an audit, update the source document's Open Questions section to reflect the resolution
04 同仓库更多 Skills
ticket-breakdown
Decompose one capability area's requirements for one change into implementable tickets with Priority, Value, acceptance criteria, Prior Art, Output contracts, Known Hazards, dependency ordering and relative sizing: one TICKET-NNN.md per ticket plus backlog.md, in the change's tickets directory. Use when a specification is approved and the team needs work items, such as 'break this spec into tickets' or 'create the backlog for search'. Not for implementing a ticket (delivery) or ordering whole capability areas (dependencies).
technical-design
Translate specifications, constraints and dependencies into architecture decisions (AD-XXX), component boundaries, data model and interface contracts under .gener8v/technical-design/. Use when technology or architecture choices must be settled before tickets are written, such as 'which datastore should we use' or 'design the components for search'. Skip it when the approach is obvious and uncontested. Not for judging an architecture that has already shipped (architecture-review).
specification
Expand one capability area from .gener8v/prd.md into a functional specification with atomic, testable [PREFIX]-REQ-XXX requirements, behaviors, edge cases and open questions under .gener8v/specifications/. Use when a PRD capability area needs elaboration before constraints, technical design or tickets, or a change brief still marks an area as pending specification, such as 'spec out the search area' or 'write the requirements for billing'. Not for the whole product (planning) or work items (ticket-breakdown).
setup
Bootstrap the gener8v pipeline in a project: create .gener8v/, copy the conventions, generate pipeline-state.yaml, and add the pipeline directives to CLAUDE.md. Use when the user says 'set up gener8v' or 'initialize the pipeline', when a project has no .gener8v/prd.md, or after a plugin upgrade to refresh the conventions. Not for deciding what to do next on a project already on the pipeline (orchestrate).
security-review
OWASP-informed, code-level security review of delivered code: injection, authentication and authorization, data exposure, configuration, dependencies, cryptography and logging, with attack scenarios for Medium+ findings and compliance constraints (CC-XXX) treated as Critical. Use after a delivery, especially one touching input handling, auth, sensitive data or external integrations, such as 'security review TICKET-007' or 'check what this delivery shipped for injection or auth bypass before we merge'. Not for a whole-codebase OWASP posture assessment (owasp-top10-review) or prompt-injection risk in LLM features (owasp-llm-top10-review).
rot-watch
Detect decay in code that is being actively written: measure six signals (packaging drift, dependency direction, comment language, growth slopes, tests, the detectable subset of SOLID) against a recorded baseline and report only what moved, at .gener8v/rot/. Use once code has been delivered and again every few deliveries, before a release, or when asked 'is the codebase getting worse' or 'has this module drifted'. The first run records the baseline and reports nothing. Not for one delivery's quality (quality-review), defects (defect-sweep) or whether the architecture was right (architecture-review).