orchestrator: Skill for Claude Code

QA Doc Governance

Run a repeatable governance loop for QA documentation quality, consistency, and discoverability.

Workflow

1. Baseline audit.
2. Classify findings by severity and scope.
3. Apply targeted remediation.
4. Sync index and governance artifacts.
5. Validate and publish audit result.

Step 1: Baseline Audit

1. Run scripts/qa-doc-lint.sh.
2. Run ./.claude/skills/qa-doc-governance/scripts/run-audit.sh for expanded metrics.
3. If needed, read references/policy-checklist.md for rule definitions.

Step 2: Classify Findings

Use this priority order:

1. P0: Broken navigability or unusable test flow. : Examples: missing checklist, impossible auth/session steps, README index drift.
2. P1: Governance drift. : Examples: too many scenarios in one file, missing UI entry visibility in UI-facing docs.
3. P2: Style consistency improvements. : Examples: naming alignment, wording normalization.

Step 3: Remediate

Apply these rules in order:

1. Fix executable correctness first. : Replace non-executable auth/session checks with explicit methods (incognito/private window, clear session cookie, explicit sign-out).
2. Enforce mock-fixture-only for orchestrator workflows. : QA docs must reference fixtures/manifests/bundles/* mock fixtures (echo agents), never docs/workflow/* (real AI agents). Every doc must include explicit apply -f fixtures/... in preconditions. Standalone scenario stubs must inline precondition commands or cross-reference parent doc. Severity: P0.
3. Enforce visibility-first UI flows. : UI scenarios start from visible entry points (sidebar, tab, button, quick links), not direct URL.
4. Enforce scenario cap. : Keep each file <=5 numbered scenarios. Split long files into base/advanced or topic-specific docs.
5. Keep checklists mandatory. : Every QA doc includes ## Checklist / ## Regression Checklist (or localized equivalent).

Step 4: Sync Governance Artifacts

1. Update docs/qa/README.md so index matches current docs.
2. If this repo uses docs/qa/_manifest.yaml, regenerate it with scenario counts and governance flags.
3. If QA behavior changes affect security/UIUX expectations, add alignment notes to: : docs/security/README.md, docs/uiux/README.md.
4. Check CHANGELOG.md consistency. : Entries under [Unreleased] have not shipped, so a stale one will publish as a false statement. Verify no unreleased entry describes a mechanism the repo has since removed or replaced, that removals appear under ### Removed, and that user-visible incompatibilities are recorded with the exact diagnostic users will hit. Released sections are historical and stay as written.