qa-hvn

Files (7)

• SKILL.md
• openai.yaml · agents/
• issue-template.md · references/
• report-template.md · references/
• severity-rubric.md · references/
• verification-matrix.md · references/
• validate-skill.sh · scripts/

SKILL.md (first lines)

# QA-HVN

## Mission and boundary

QA-HVN turns a requested audit into an evidence-backed release-readiness decision. It discovers the product and repository before testing, derives a product-specific matrix, searches broadly for distinct failures, fixes confirmed root causes when authorized, adds regression coverage, and re-verifies the affected and adjacent surfaces.

The default goal is exhaustive discovery within the named repository and its documented runtime boundaries. The 200-unique-issue figure is a search target, not a quota. Stop when the search is saturated, the product is smaller than the target, or a real boundary prevents further evidence. Never invent findings to reach a number.

QA-HVN is explicit-only. Do not invoke it for a narrow bug fix, a routine test run, a lightweight review, or a quick smoke test. At installation time, validate the skill and run only the disposable report-only smoke test; do not run a real audit.

## Operating contract

1. Read the repository-local `AGENTS.md`, contribution rules, package manifests, test commands, deployment notes, and existing issue or release guidance before choosing actions.
2. Establish the canonical checkout, current branch and commit, dirty state, worktree list, runtime targets, test accounts, service boundaries, and permitted environments. Preserve unrelated changes and machine-local credentials.
3. Use the smallest safe action that produces decisive evidence. Prefer existing fixtures, staging, disposable accounts, local emulators, and reversible data. Do not use production data or production credentials unless the user explicitly authorizes that exact operation.
4. Make changes only when the request authorizes remediation. A report-only audit records findings and reproduction evidence without editing source, opening pull requests, or changing external state.
5. Keep a continuously updated Markdown report. Write each discovery, reproduction, root cause, change, verification result, limitation, and decision while the audit proceeds; do not reconstruct the record from memory at the end.
6. Use exact statuses and verdicts from this skill. Distinguish a source assertion, a passing test, a runtime observation, a delivery check, and an external or human gate.

## Permitted autonomy and escalation

Proceed autonomously through repository discovery, local test execution, disposable fixture setup, isolated worktree creation, safe source changes, regression tests, report updates, and draft pull requests when the user requested them. Ask or escalate only when the next action requires a missing credential, production access, destructive data mutation, paid service, account ownership, signing or store authority, a protected SDK boundary, a legal or licensing decision, or a material scope choice not recoverable from repository evidence.

When escalation is required, record the exact blocked action, owner, evidence already collected, safest next action, and whether the block affects the verdict. Do not turn lack of access into a guessed pass.

## Protected boundaries

Treat public SDK contracts, documented API shapes, persisted schemas, authentication and authorization rules, privacy promises, platform restrictions, external service contracts, and release configuration as protected boundaries. Do not weaken, bypass, stub over, or silently change one to make a test pass. If a boundary appears defective, prove the behavior, propose the smallest compatible correction, and mark compatibility or owner review as a gate when it cannot be verified locally.

## Discovery and test design

Derive the matrix from the actual product rather than applying a generic checklist. Map user roles, critical journeys, state transitions, input classes, permissions, devices or browsers, network conditions, persistence, background work, integrations, observability, and deployment paths. Include happy paths, empty states, invalid input, retries, cancellation, interruption, timeout, offline or degraded service, duplicate delivery, permission denial, stale data, migration, upgrade, rollback, and recovery.

Record the baseline before fixes: build and test commands, known failures, environment identity, seed data, available targets, and a timestamp. Classify every candidate as a distinct user-visible failure, a root-cause family, an observation requiring more evidence, or a duplicate of an existing issue.

## Twelve-agent ownership model

Use isolated subagents or equivalent bounded work lanes when the repository and task support them. The coordinator owns the graph, deduplication, report, integration order, and final verdict. Assign each lane a clear input, output, evidence requirement, and write boundary:

1. Coordinator and integrator: discovery, graph, ownership, deduplication, report, merge order, and final decision.
2. Product journeys: roles, core flows, state transitions, empty and recovery paths, and user-visible correctness.
3. UI and interaction: layout, navigation, input, interruption, responsive behavior, and observable interaction defects.
4. Platform and runtime: build variants, lifecycle, concurrency, device or browser coverage, and environment-specific behavior.
5. API and integration: contracts, authentication flows, retries, timeouts, rate limits, webhooks, and compatibility.
6. Data and synchronization: persistence, migrations, cache invalidation, ordering, idempotency, offline behavior, and conflict recovery.
7. Security and privacy: trust boundaries, authorization, secrets, injection, abuse paths, data exposure, and secure defaults.
8. Accessibility: keyboard, screen reader, focus, semantics, contrast, motion, dynamic type, touch targets, and error communication.
9. Performance and stress: latency, throughput, memory, CPU, battery, large inputs, concurrency, soak, and resource cleanup.
10. Deployment and operations: packaging, configuration, observability, health checks, migrations, rollback, and release artifacts.
11. Cross-platform and compatibility: supported OS versions, browsers, form factors, localization, time zones, and upgrade paths.
12. Adversarial regression: boundary values, malformed inputs, interruption, fault injection, previously fixed areas, and adjacent regressions.

Agents may combine lanes when the product is small, but ownership and evidence must remain explicit. No two lanes should independently edit the same files or mutate the same environment. The coordinator resolves overlaps before integration.

## Isolation, graph, and loop

For repository changes, create task-owned branches or worktrees from the exact audited commit. Keep each lane’s changes isolated, inspect the diff before integration, and preserve the user’s pre-existing dirty state. Use a directed graph of phases and evidence: discovery fans out to independent lanes; findings flow into root-cause clusters; fixes flow into regression and adjacent checks; all paths fan in to integration and the release verdict. A node is complete only when its stated output and evidence exist.

Each remediation loop is bounded and explicit:

`observe -> reproduce -> classify -> diagnose -> change -> verify -> regress -> update report`

Set an owner, objective, evidence requirement, iteration limit, and stop condition before entering a loop. A failed verification returns to diagnosis with new evidence; it is not a blind retry. Stop when the root cause is fixed and regression evidence passes, when the issue is proven external or protected, or when the bounded budget is exhausted and the report records the remaining uncertainty.

## Finding and remediation protocol

For every candidate, capture the exact surface, preconditions, steps or test, expected behavior, actual behavior, environment, evidence path, severity, confidence, root-cause hypothesis, and affected versions. Reproduce independently when practical. Group only findings with the same root cause and materially the same remediation; retain separate user impacts and test cases.

For confirmed project-owned defects, diagnose the root cause before editing. Apply the smallest compatible fix, add or strengthen regression coverage, run targeted verification, then run adjacent and risk-appropriate broad checks. Re-open the original reproduction and test failure paths, not merely the new unit test. Record files, commit or branch, commands, results, and any unverified dimensions.

Use the severity rubric in `references/severity-rubric.md`. A finding may be `P0`, `P1`, `P2`, `P3`, or `P4`; severity is about impact and exploitability, not implementation effort. Do not lower severity because a workaround exists unless the workaround is verified and changes user impact.

## Evidence matrix

Complete the matrix in `references/verification-matrix.md` for each critical journey and each high-severity finding. The minimum evidence layers are source and configuration inspection, deterministic test output, failure-path or boundary tests, runtime interaction, accessibility inspection, performance or stress evidence where relevant, security and privacy evidence, data-integrity evidence, deployment or packaging evidence, and exact delivery or external-gate truth. Mark unavailable evidence `UNVERIFIED` with the reason.

Passing source checks do not prove runtime behavior. Passing local tests do not prove deployment, store, production, external-review, or human readiness. A green CI run does not clear an untested device, role, data migration, or integration boundary.

## Continuous report and exact statuses

Maintain the report using `references/report-template.md`. Use only these issue statuses:

- `DISCOVERED`: candidate recorded, reproduction or evidence still being established.
- `CONFIRMED`: reproducible or otherwise decisive evidence establishes the behavior.
- `IN_REMEDIATION`: an owned fix is actively being developed in isolation.
- `FIXED`: the root-cause change is complete but required verification is incomplete.
- `VERIFIED`: targeted and required regression evidence passes.
- `DUPLICATE`: same root cause and materially same behavior as another finding; link both records.
- `EXTERNAL_BLOCKER`: blocked by an external owner, unavailable authority, or protected boundary.
- `UNVERIFIED`: evidence is incomplete or contradictory; never treat as a pass.
- `DEFERRED_BY_USER`: the user explicitly deferred the finding; include the narrower supported claim.

For each update, include the current graph frontier, active owners, issue counts by status and severity, commands run, report path, changed files, and the next bounded action. Reports should be append-friendly and readable while the audit is still running.

## Release-readiness decision

Use exactly one final verdict:

- `SHIP`: no open P0 or P1 issue, critical journeys and required evidence pass, and no unverified release-critical boundary remains.
- `SHIP WITH KNOWN RISKS`: no release-blocking P0 or P1 issue remains, but explicitly accepted P2 or lower risks, external gates, or bounded evidence gaps remain and are documented with owners and impact.
- `DO NOT SHIP`: any unresolved P0 or P1 issue, failed critical journey, unsafe security or integrity boundary, failed migration or rollback, missing required release artifact, or material unverified risk prevents a defensible release.

The verdict must name the audited commit, report path, issue totals, fixed and verified changes, remaining risks, external or human gates, unverified areas, and exact next actions. “No issues found” is valid only when the search scope, matrix, evidence, and saturation rationale are recorded.

## References

Use the companion templates and rubrics in this package:

- `references/report-template.md` for the live Markdown report.
- `references/issue-template.md` for normalized finding records.
- `references/verification-matrix.md` for claim-to-evidence mapping.
- `references/severity-rubric.md` for impact and release classification.

From henryvn27/agent-skills, MIT.

More from henryvn27/agent-skills