quality-studio 0.0.1__tar.gz

quality_studio-0.0.1/.claude/skills/.shared/simplicity-principals.md

@@ -0,0 +1,68 @@
+# Simplicity Principles
+
+> "Simplicity is the ultimate sophistication" — the north star for every change
+> made to this codebase.
+
+Simplicity is not about fewer lines of code. It is about **fewer concepts**,
+**predictable flows**, and **easy reversal**. Complexity is debt — every
+abstraction is a bet that we understand the problem space. Start simple. Add
+complexity only when forced by real requirements. Keep the escape hatches open.
+
+---
+
+## Core Rules
+
+| Rule | What it means in practice |
+|------|--------------------------|
+| **One thing per file** | Each file should do one thing and be findable in under 10 seconds. If a file is growing, it is probably doing too much — split it. |
+| **Domains own their folders** | Folder structure reflects domain boundaries, not framework conventions. If a folder needs a README to explain its structure, simplify the structure instead. |
+| **Standardise the stack** | Reuse before you build. Use the established patterns, hooks, helpers, and abstractions that already exist. Introduce new ones only when the existing toolset genuinely cannot solve the problem. |
+| **Push complexity to the edges** | Business rules in pure functions. I/O at the boundaries. Minimal logic inside framework callbacks, route handlers, or render functions. |
+| **APIs must be tiny** | Expose the minimum interface needed. Every extra parameter, flag, or overload is a contract that must be maintained forever. |
+| **Resist premature abstraction** | A base class or generic utility with one concrete implementation is not an abstraction — it is indirection. Wait for the second or third real case. |
+| **Keep escape hatches open** | Before adding a pattern, ask: can we delete this later without a large rewrite? If not, simplify until the answer is yes. |
+
+---
+
+## Line Count Policy
+
+Line count is a **review trigger, not a completion gate**. A long file can be a
+sign that responsibilities are mixed, but LOC is not a simplicity violation by
+itself. Do not split a cohesive file solely to satisfy a numeric threshold when
+the split would add indirection, create new concepts, scatter one flow across
+files, or make the behavior harder to explain.
+
+When a file crosses a LOC trigger, review the actual simplicity criteria:
+
+- Does the file still have one clear responsibility?
+- Can the flow still be explained in under 60 seconds?
+- Would a split make the next change easier to find, test, and reverse?
+- Would keeping the file together be simpler than introducing a new boundary?
+
+Prefer the simpler design, even when that means accepting a non-blocking LOC
+advisory.
+
+---
+
+## PR Checklist
+
+Before any change is complete, verify:
+
+- [ ] Can a new dev explain this flow in **< 60 seconds**?
+- [ ] Did we add a **new concept**? If yes, it must be justified by a real requirement.
+- [ ] Can we **delete this later** easily?
+- [ ] Are **errors observable in one place**?
+
+---
+
+## Applying These Principles
+
+Every skill in this repository enforces the simplicity standard at its quality
+gate. When delivering work — whether implementing, reviewing, auditing, or
+planning — apply these questions before finalising output:
+
+1. Is there a simpler way to achieve the same outcome?
+2. Does this introduce a concept that does not already exist in the codebase?
+3. Will a colleague be able to modify or remove this safely in six months?
+4. If this fails, will the failure be obvious and localised?
+

quality_studio-0.0.1/.claude/skills/backend-error-guard/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: backend-error-guard
+description: >
+  Audit and improve backend and infrastructure error handling in the
+  qa-studio codebase. Use when reviewing FastAPI routes (backend/api/), the
+  change-set + history write path (services.py, history.py), Anthropic SDK
+  retries (generation/anthropic_client.py), GitHub auto-issue creation
+  (issues.py, github.py), junit-xml ingest (runs.py), Docker exit behavior,
+  and CI failures. Produces a prioritized findings report — does not modify
+  code.
+tool_hints:
+  - "Every finding must cite a concrete file:line in src/quality_studio/"
+  - "Treat the change-set wrapper as non-negotiable — flag any write path that bypasses services.py"
+  - "Anthropic and GitHub clients already retry; do not recommend a second retry layer"
+  - "No code changes — output is the audit report only"
+composition_hints:
+  - "Pair with backlog-author to file findings as GitHub Issues, then backlog-executor for delivery"
+  - "Pair with python-agent to implement fixes after the audit is reviewed (via backlog-executor)"
+  - "Pair with bugbuster when a specific failing test or traceback motivates the audit"
+  - "Pair with tech-auditor when the error-handling audit reveals broader architectural concerns"
+---
+
+# Backend Error Guard
+
+Audit backend and runtime-layer error handling methodically, then produce a
+prioritized improvement plan grounded in the actual qa-studio architecture.
+
+This skill is specialized. Use it when the primary task is error-handling audit,
+hardening, or redesign. For general backend feature work, use `python-agent`.
+
+## Standards Precedence
+
+The change-set audit spine takes precedence over generic audit guidance.
+
+- The Studio's only write path is through `src/quality_studio/services.py` (records) and the runs/issues writers in `runs.py` / `issues.py`. Errors that bypass the change-set wrapper break audit and time-travel.
+- Anthropic and GitHub clients have retry policies built in (`src/quality_studio/generation/anthropic_client.py`, `src/quality_studio/github.py`); do not wrap them in a second retry layer.
+- Configuration loads through `src/quality_studio/config.py`. Never read `os.environ` directly inside Studio code — use the resolved config object.
+- All errors that abort a `quality` CLI invocation must exit non-zero with a message that names the file path or DB row at fault (CI gates depend on it).
+
+## Primary Audit Scope
+
+Review the backend and adjacent runtime layers for:
+
+- bare `except:` and broad `except Exception:` blocks
+- swallowed exceptions or logs without tracebacks
+- inconsistent exception-to-response mapping in FastAPI routes and middleware
+- incorrect HTTP status semantics
+- missing or fragmented custom exception hierarchies
+- provider, database, HTTP client, and file-service errors that lose context
+- background or async task failures that are dropped silently
+- health checks that do not reflect real degraded states
+- missing startup validation for required configuration
+- Docker, compose, and CI failures that exit without enough context
+
+## Workflow
+
+1. **Ground in the actual implementation first.**
+   - Read the relevant route, service, and support modules before making recommendations.
+   - Start with the Studio's primary write path: [src/quality_studio/services.py](src/quality_studio/services.py) and [src/quality_studio/history.py](src/quality_studio/history.py).
+   - Inspect external boundaries that can fail: [src/quality_studio/generation/anthropic_client.py](src/quality_studio/generation/anthropic_client.py), [src/quality_studio/github.py](src/quality_studio/github.py), [src/quality_studio/runs.py](src/quality_studio/runs.py) (junit-xml parse + subprocess), [src/quality_studio/target_repo.py](src/quality_studio/target_repo.py) (filesystem reads), [src/quality_studio/db.py](src/quality_studio/db.py) (asyncpg).
+   - Inspect Dockerfile, docker-compose.yml, and the CI workflow files for failure modes that exit without enough context.
+
+2. **Audit the current state before proposing fixes.**
+   - Search for `except Exception:` and bare `except:` first.
+   - Identify where tracebacks are lost because `logger.error(...)` is used
+     inside `except` blocks instead of traceback-preserving logging.
+   - Check whether request-scoped identifiers such as `request_id` are carried
+     into logs and error responses.
+   - Distinguish legitimate defensive compatibility wrappers from production
+     error-swallowing.
+
+3. **Assess framework-level handling.**
+   - Verify whether FastAPI exception handlers or middleware return a consistent
+     error shape.
+   - Confirm that 4xx versus 5xx behavior matches the failure source.
+   - Identify routes that do ad hoc translation instead of relying on a central
+     exception mapping strategy.
+
+4. **Assess operational surfacing.**
+   - Review startup validation, background task handling, health checks,
+     container shutdown behavior, and CI error visibility.
+   - Prefer fail-fast startup for missing required config.
+   - Flag hidden retries, fallback paths, or shutdown paths that suppress root
+     cause context.
+
+5. **Produce the audit deliverables.**
+   - Write findings to `docs/audit/error/audit-report.md`.
+   - Write the prioritized plan to `docs/audit/error/improvement-plan.md`.
+   - If these files already exist, preserve validated content and extend them
+     rather than overwriting unrelated sections.
+
+## Audit Output Contract
+
+Write the backend findings into `docs/audit/error/audit-report.md` using this
+shape:
+
+```markdown
+## Audit Report
+
+### Summary
+- Layers reviewed: API / Backend, Infrastructure / Pipeline
+- Total issues found:
+- Critical: / High: / Medium: / Low:
+
+### Findings Table
+| ID | Layer | Location | Issue | Severity | Impact |
+|----|-------|----------|-------|----------|--------|
+```
+
+Rules:
+
+- Use stable IDs such as `BE-001`, `INF-002`.
+- `Location` must point to concrete files, modules, endpoints, scripts, or
+  runtime assets.
+- `Impact` must explain the operational consequence, not restate the issue.
+- Prioritize evidence-backed findings. Do not speculate.
+
+## Improvement Plan Contract
+
+Write the backend plan into `docs/audit/error/improvement-plan.md` using this
+shape:
+
+```markdown
+## Improvement Plan
+
+### Quick Wins (< 1 day each)
+| ID | Action | Layer | Owner |
+|----|--------|-------|-------|
+
+### Medium-term (1–3 days each)
+| ID | Action | Layer | Owner |
+|----|--------|-------|-------|
+
+### Strategic (requires design/discussion)
+| ID | Action | Layer | Owner |
+|----|--------|-------|-------|
+
+### Recommended Tooling
+- Logging:
+- Monitoring / Alerting:
+- Error tracking:
+
+### Proposed Exception Class Structure
+[Provide a Python code scaffold]
+
+### Success Criteria
+- [ ] No bare except blocks in production code
+- [ ] All API errors follow a consistent response schema
+- [ ] Developers receive traceback + context; users receive safe messages
+- [ ] Background task failures visible in monitoring
+- [ ] Error rates and types tracked in a dashboard
+```
+
+## Backend Improvement Standards
+
+Use these standards when forming recommendations or implementing fixes:
+
+- Catch specific exceptions where the code can recover meaningfully.
+- If the code cannot recover, add context and re-raise or let centralized
+  handling translate the failure.
+- Prefer traceback-preserving exception logging inside `except` paths.
+- Preserve safe user-facing messages while keeping full internal context in logs.
+- Centralize exception-to-response mapping instead of duplicating response logic
+  across route handlers.
+- Standardize on one application-level exception hierarchy for service and API
+  failures. Extend existing base types before adding new root classes.
+- Reconcile the ErrorGuard target shape `{ code, message, details?, request_id?,
+  trace_id? }` with the current canonical response model before proposing API
+  contract changes. Do not create a second competing schema.
+- Ensure third-party failures preserve provider, status, timeout, and retry
+  metadata when available.
+
+When proposing a scaffold, keep it close to the current codebase shape, for
+example:
+
+```python
+class AppError(Exception):
+    code: str
+    http_status: int
+
+
+class ValidationError(AppError): ...
+class NotFoundError(AppError): ...
+class AuthorizationError(AppError): ...
+class ConflictError(AppError): ...
+class ExternalServiceError(AppError): ...
+class TimeoutError(AppError): ...
+```
+
+## Boundaries With Other Skills
+
+- Use `python-agent` for normal backend implementation once the error-handling
+  direction is clear.
+- For a specific failing test or traceback, hand off to `test-runner` after the audit narrows the scope.
+- Use `test-author` to design backend error-path tests.
+- Use `test-runner` to execute backend verification and produce test reports.
+- Use `doc-writer` only when the primary task is broader API or operational
+  documentation beyond this audit output.
+
+## Operating Style
+
+- Highest-impact gaps first.
+- Findings before plan.
+- Evidence before recommendation.
+- Prefer minimal, enforceable standards over broad rewrites.
+- Call out ambiguity explicitly when a recommendation depends on a repository
+  decision that has not yet been made.
+
+---
+
+## Simplicity Standard
+
+See [`../.shared/simplicity-principals.md`](../.shared/simplicity-principals.md) for the full specification.
+
+Apply the PR checklist before finalising any output:
+- [ ] Can a new dev explain this flow in **< 60 seconds**?
+- [ ] Did this add a new concept? If yes, it must be justified.
+- [ ] Can this be deleted later easily?
+- [ ] Are errors observable in one place?

quality_studio-0.0.1/.claude/skills/backlog-author/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: backlog-author
+description: >
+  Analyze a feature, bug, gap, or implementation request and create a GitHub
+  Issue in pixenbio/qa-studio that follows the repository's backlog patterns.
+  Use this when the user wants a new backlog item written from repository
+  evidence, including title, scope, verified current state, requirements,
+  acceptance criteria, and implementation guidance where appropriate. Always
+  use the GitHub CLI (`gh`) and prefer `gh api graphql` for issue reads,
+  searches, and mutations.
+tool_hints:
+  - "Read references/output-format.md and then the linked type-specific format doc before drafting"
+  - "Review at least 2-3 similar existing GitHub issues before writing a new one, covering both open and closed issues for prior decisions and scope, not to rediscover the template"
+  - "Choose the native GitHub issue type first (Bug, Feature, Task), then use the matching local format reference"
+  - "If the local references and the live issue corpus disagree, update the local references first instead of silently following issue drift"
+  - "For bug issues, explicitly write how the fix prevents the same bug from happening again and require regression coverage for that failure mode"
+  - "For any code-changing issue, require test-author to author/update tests and quality records before test-runner executes them"
+  - "For issues that cross the target-agnostic boundary, the change-set audit spine, baseline, or layered configuration, the issue must say so and cite the source files that enforce those invariants (CI lints, services.py, generation/validators.py, config.py)"
+  - "For issues that cross contract boundaries (Studio capability against minimal_target), require explicit contract test coverage in tests/contract/"
+  - "Separate verified current state from proposed work; do not present speculation as already implemented"
+  - "Use repository evidence from src/quality_studio/, www/, tests/, and docs/ before drafting requirements"
+  - "During fact generation, share verified facts and open questions with the user and ask concise follow-up questions before finalizing the backlog item when product or scope details remain unclear"
+  - "Add a `Skill Routing` section to each new issue body that points to `backlog-executor` plus only the relevant companion skills for the scoped work"
+  - "Use `gh api graphql` `createIssue` to create new GitHub issues; never use MCP tools"
+  - "Use `gh api graphql` `repository.issue` queries to read existing issues before enrichment"
+  - "Use `gh api graphql` mutations (`updateIssue`, `addLabelsToLabelable`, `removeLabelsFromLabelable`) to update issue body and labels"
+  - "Use the `v:*` label set on existing GitHub issues to infer v-band targeting; if uncertain, ask the user before filing"
+composition_hints:
+  - "Use before implementation when a request is still exploratory, cross-cutting, or needs a durable project record"
+  - "Pair with backlog-executor after the item is approved and ready for delivery"
+  - "Receive handoffs from solution-designer (fact pack), product-advisor (decision), or bugbuster (confirmed bug)"
+  - "Use with doc-writer only if the backlog work requires source-verified documentation changes"
+  - "Use in enrich mode when a quality-studio:auto issue (created by `quality runs ingest` on test failure) needs codebase analysis and structured body"
+---
+
+# Backlog Item Creator
+
+Create GitHub Issues as backlog items using qa-studio's repository patterns. This skill is for analysis and backlog authoring, not feature implementation.
+
+Read [`references/output-format.md`](references/output-format.md) at the start of every task. It defines the active GitHub issue types, required metadata, and links to the type-specific body formats for qa-studio.
+
+Before live GitHub reads or mutations, confirm `gh` is installed and authenticated (`gh auth status`). If unavailable, produce a ready-to-run issue payload and exact command instead of retrying live mutations.
+
+When authoring a backlog issue that would touch `src/quality_studio/services.py` (change-set + history writes), `src/quality_studio/generation/` (LLM pipeline + JSON-schema enforcement), the target-agnostic boundary, or the opinionated baseline, read those source files directly and ground the issue's verified-state and acceptance criteria in the actual invariants they enforce.
+
+## Purpose
+
+Use this skill when the user wants one of these outcomes:
+
+- a new GitHub Issue for a feature or enhancement
+- a backlog record for a bug, contract gap, or boundary concern
+- an implementation plan captured as a GitHub Issue
+- a progress-tracking issue derived from existing work
+
+Do not use this skill to implement the change itself. If the user wants delivery, hand off to `backlog-executor` after the issue exists.
+
+## Operating Modes
+
+This skill has two modes depending on whether the item originates from a new request or from an external source.
+
+### Mode A — Create new
+
+Use when the user requests a new backlog item. This is the default mode.
+
+1. Analyze nearby code, docs, and similar issues across both open and closed issue states
+2. Build a fact pack with verified current state, inferred gaps, and open questions
+3. Interact with the user to resolve material unknowns before drafting the final issue body
+4. Create GitHub Issue via `gh api graphql` (`createIssue` mutation), then set type and parent metadata as needed
+5. Report the issue number to the user
+
+### Mode B — Enrich existing
+
+Use when a GitHub issue already exists (e.g., a `quality-studio:auto` issue auto-created by `quality runs ingest` from a test failure, or a Sentry-style import) and needs structured analysis.
+
+1. Read existing GitHub issue via a GraphQL `repository.issue(number: <NN>)` query — extract title, body, labels, references
+2. Analyze codebase: read source files implicated, check existing tests, inspect related code
+3. Update issue body via the GraphQL `updateIssue` mutation with structured analysis: Root Cause, Affected Code, Test Coverage, Fix Direction, Acceptance Criteria, Skill Routing
+4. Set missing labels (type, area, priority) via GraphQL label mutations using the qa-studio label enum
+
+## Non-Negotiables
+
+- Write from repository evidence first. Read code, tests, existing docs, and nearby issues before drafting.
+- Search both open and closed GitHub issues for similar backlog items, prior decisions, and earlier attempts before drafting a new one.
+- Keep verified facts and proposed future work clearly separated.
+- Do not claim something is broken, implemented, or validated unless the repository proves it.
+- Follow the local type-specific format reference for the chosen GitHub issue type; do not rediscover section order from issue search results.
+- If the local references are missing, ambiguous, or stale for the requested work, update the local references first before drafting or creating the issue.
+- If the local references and the current issue corpus disagree, stop and update the local references before drafting or creating the issue. Do not silently follow the drift.
+- For bug issues, explicitly document the repeat-prevention boundary: how the planned fix stops the same failure mode from recurring, not just how it resolves the current symptom.
+- When a workflow or bug-contract change needs verification, route test design through `test-author` and test execution through `test-runner`; do not describe verification as complete without the proper skill handoff.
+- Every code-changing backlog issue must make the testing sequence explicit: `test-author` authors or updates quality records and executable tests first; `test-runner` executes the relevant suites, records measured results, and delegates contract-layer execution against `postgres-quality:5433` to `integration-runner` when applicable. Do not write issue text that allows ad hoc test creation and raw command output to substitute for this sequence.
+- For every issue, assess whether the planned work crosses Studio boundaries:
+  - change-set + history audit spine (no DB writes outside `services.py`)
+  - opinionated baseline (validations[], risk_level, outcome tag, three mandatory validate rules)
+  - layered configuration (Target → Domain → Records)
+  - Anthropic SDK boundary (cost cap, prompt caching, structured-output validation)
+  - GitHub write boundary (auto-issue creation, PAT scope, dedup)
+  Acceptance criteria must explicitly preserve these boundaries.
+- During fact generation, stop and ask the user targeted questions when product intent, scope boundaries, rollout expectations, or acceptance details are still ambiguous in a way that would materially change the backlog item.
+- Every new backlog issue must include a `Skill Routing` section that names `backlog-executor` and the relevant repository skills needed to deliver the work.
+
+## Regression Prevention
+
+Apply this guardrail on every `backlog-author` task:
+
+1. Choose the native GitHub issue type first.
+2. Open the matching local reference and treat it as the format source of truth.
+3. Search GitHub issues only after that, and only for prior decisions and scope context.
+4. Before issue creation or update, compare the draft against the matching local reference and resolve any mismatch intentionally.
+5. For bug issues, make the draft state how the implementation and regression coverage will prevent the same bug from recurring.
+6. When this workflow changes, add or update automated contract tests for the skill/reference rules with `test-author`, then run them with `test-runner`.
+
+## Workflow
+
+### 1. Gather context
+
+Before writing:
+
+1. Read `references/output-format.md`.
+2. Determine the native GitHub issue **Type** first: `Bug`, `Feature`, or `Task`.
+3. Open the matching local format reference from `references/` and use it as the source of truth for metadata and section order.
+4. Review at least two existing GitHub Issues that overlap with the requested domain or problem, covering both open and closed states when possible. Use GraphQL search queries such as `repo:pixenbio/qa-studio is:issue is:open ...` and `repo:pixenbio/qa-studio is:issue is:closed ...`, then use the shared `repository.issue` query pattern for the most relevant matches.
+5. Use issue review for prior decisions, scope boundaries, parents, siblings, and historical context. Do not use issue review to infer the body template.
+6. If the local references feel outdated while reviewing the current issue corpus, update the references and their contract tests before continuing with issue authoring.
+7. If the request is a bug or regression, identify the repeat path up front: what allowed the same failure mode through before, and what test coverage should stop it from returning.
+8. Identify whether contract coverage (against `minimal_target` or a live target) is relevant by checking for change-set, generation, runs, issues, baseline, or boundary surfaces in the planned work.
+9. Identify the testing layers affected by the planned work. Record whether `unit` and `contract` are in scope, out of scope, or blocked. For every in-scope layer, the issue must require `test-author` coverage authoring before `test-runner` execution.
+10. If `contract` is in scope, draft explicit acceptance criteria requiring `test-author` to publish or update the corresponding test against `tests/fixtures/minimal_target/` and require `test-runner` (delegating to `integration-runner`) to execute it before the issue is complete.
+
+### 2. Build factual context
+
+Read only the files needed to support the item:
+
+- implementation files in `src/quality_studio/`
+- tests in `tests/unit/`, `tests/contract/`
+- docs/ (overview, cli-reference, target-repo-contract, shipped-skills)
+- migrations in `src/quality_studio/migrations/`
+- existing issues that overlap with the same area
+
+Resolve source, test, doc, and migration paths with `rg --files` or `test -f` before citing them in the issue body. If a path from memory, logs, or an older issue is stale, search for the symbol, route, migration number, or test name and record the current path only.
+
+Capture:
+
+- what exists today
+- what is missing or unclear
+- what the backlog item is trying to change
+- what constraints or dependencies already exist
+
+Turn this into a compact fact pack before drafting:
+
+- `Verified Facts`: repository-supported statements only
+- `Prior Issue Context`: what related open and closed issues already established
+- `Open Questions`: missing decisions, unclear requirements, or disputed assumptions
+
+If the requested work mixes more than one stable deliverable, note that before drafting and prefer restructuring it as prerequisite plus follow-up, or parent plus child issues, rather than widening one issue body to cover everything.
+
+If `Open Questions` contain anything that would materially change scope, acceptance criteria, labels, or routing, pause and ask the user concise follow-up questions before moving on. Do not silently fill these gaps with assumptions when the user can answer them.
+
+When interacting with the user during fact generation:
+
+- summarize the verified facts first
+- ask only the minimum set of questions needed to unblock drafting
+- preserve the original question text and record the user's answer beneath it using `**Answer:**`
+- carry unresolved items into the backlog issue's `## Open Questions` section rather than inventing certainty
+
+### 3. Choose the issue type and local format
+
+Use the local references to choose the native GitHub issue type and its closest format variant:
+
+- `Bug`: defects, regressions, contract mismatches, misleading failures, or observability gaps in existing behavior
+- `Feature`: new capabilities, contract additions, cross-cutting initiatives, or epics
+- `Task`: bounded delivery slices such as QA automation, coverage expansion, migrations, implementation follow-ups, and similar scoped work
+
+### 4. Draft the issue body
+
+Write the issue body using the chosen type-specific local format and only repository-supported claims.
+
+Required qualities:
+
+- concise title (under 70 characters, action-verb-first)
+- overview that states why the item exists
+- explicit separation of current state vs planned work
+- requirements or phased plan when implementation is in scope
+- for bug issues, an explicit repeat-prevention statement that explains how the same failure mode will be blocked from returning
+- a `Skill Routing` section for active work that tells the implementer which repository skills to use
+- acceptance criteria
+- contract-test authoring and execution acceptance criteria when the issue touches contract boundaries (change-set spine, generation pipeline, runs/issues, baseline)
+- a testing acceptance section that separates `test-author` responsibilities from `test-runner` responsibilities
+- references to real file paths when they materially support the claim
+- a v-band assignment (v1 / v1.5 / v2 / v3) matching the `v:*` GitHub label convention; confirm with the user when unsure
+- when the scope mixes foundation work with adoption or multiple independently shippable outcomes, split the work into separate issues instead of drafting one broad execution ticket
+
+When drafting `Skill Routing`, always include `backlog-executor` for delivery handoff, then add only the skills that materially match the scoped work. Common mappings:
+
+- Studio backend or CLI work (Python: CLI, config, services, history, runs, issues, generation, backend API, models, tests): `python-agent`
+- **Next.js / React / UI work (every file under `www/`):** route through the frontend stack in priority order — **`frontend-design` first** (design + polish + production-grade interfaces; this is the priority skill for any new UI capability), then `shadcn` (component library install + composition), then `nextjs` (App Router architecture, Server Components, layouts, data fetching), plus Tailwind CSS styling guidance via the shadcn / nextjs flow. Add `react-best-practices` when the change touches multiple `.tsx` components. Reserve `python-agent` for backend API / data-layer work the UI consumes — do NOT use `python-agent` as the primary skill for UI changes.
+- new tests, regression coverage design, or quality-record authoring: `test-author`
+- test execution and durable run records: `test-runner`
+- contract execution against `postgres-quality:5433` + `minimal_target`: `integration-runner`
+- source-verified documentation changes: `doc-writer`
+- error-handling audit: `backend-error-guard`
+- root-cause debugging: `bugbuster`
+
+For bug items, workflow changes, and contract-relevant issues, default to including both `test-author` and `test-runner` unless the user explicitly wants analysis only. Add `integration-runner` when the issue should produce or run contract-layer coverage.
+
+Required testing acceptance language for code-changing issues:
+
+- `test-author` must update or add the relevant `tests/unit/` and `tests/contract/` files (and the related `quality_test_cases` records in DB when target-side cases are part of scope) before any test execution is reported.
+- `test-runner` must execute the relevant suites after the test-author work, record measured results, and clearly separate authored tests, executable tests present, and measured command results.
+- If contract coverage is in scope, `test-runner` must delegate execution to `integration-runner` (which owns `postgres-quality:5433` provisioning and `001_initial.sql` application); issue text must not permit direct host-database or ad hoc contract runs.
+
+### 5. Create the GitHub Issue
+
+1. Resolve the repository ID, label IDs, and optional milestone ID via GraphQL against `pixenbio/qa-studio`.
+2. Create the issue via GraphQL `createIssue`, then record the returned issue number, URL, and node ID.
+3. Set the native **Type** using GraphQL `updateIssue` with the issue type ID (`Bug` / `Feature` / `Task`).
+4. Set **Parent** if this issue is a child of another using the GraphQL `addSubIssue` mutation after resolving both issue node IDs.
+5. Report the issue number, type, and parent (if any) to the user.
+
+For long issue bodies or enrichment updates, avoid fragile inline heredocs. Prefer a reviewed temporary markdown file plus `--body-file`. If GitHub transport fails after the body is drafted, leave the body in a ready-to-run form and state that the remote issue was not updated.
+
+## Labels
+
+Always apply both a type label and an area label.
+
+| Label group | Values |
+|---|---|
+| Type | `type:task`, `type:feature`, `type:bug` |
+| Area | `area:cli`, `area:generation`, `area:runs`, `area:issues`, `area:api`, `area:ui`, `area:skills`, `area:docs`, `area:schema`, `area:ci` (aligned with the locked spec's Backlog Conventions; the older `area:backend` / `area:www` names are NOT used) |
+| v-band | `v:1`, `v:1.5`, `v:2`, `v:3` |
+| Special | `blocks:<issue>`, `blocked-by:<issue>`, `quality-studio:auto` (only on auto-created issues from `quality runs ingest`) |
+
+## Writing Rules
+
+- Prefer repository-specific language over generic product-management boilerplate.
+- Use tables when comparing current state, phases, or requirements.
+- Keep speculative implementation ideas under sections like `Plan`, `Implementation Sketch`, `Dependencies`, or `Open Questions`.
+- Keep `Skill Routing` concrete and selective; do not dump the full skill catalog into every item.
+- Include `Acceptance Criteria` for all new `Bug`, `Feature`, and `Task` issues.
+- For each contract-relevant issue, include explicit acceptance criteria requiring `test-author` to author the contract test against `tests/fixtures/minimal_target/` and `test-runner` (via `integration-runner`) to execute it before completion.
+- For every code-changing issue, include explicit acceptance criteria requiring `test-author` to author/update the applicable tests before `test-runner` executes and reports verification. If a layer is intentionally out of scope, require a source-backed explanation rather than leaving the layer implicit.
+- Bug issues should name the regression barrier explicitly: what test or contract check will catch the same defect next time.
+- If the code and prior issues disagree, document the mismatch instead of normalizing it silently.
+- If the item is partly implemented already, state that directly and distinguish shipped behavior from remaining scope.
+- If the requested work contains more than one stable deliverable, prefer parent plus child issues or prerequisite plus follow-up issues over one oversized ticket.
+- Preserve user answers as explicit answers to the original questions:
+  ```
+  1. Should retry be configurable per Anthropic call?
+     **Answer:** Yes — exponential backoff with max_retries from quality.toml, default 3.
+  ```
+
+## Output Expectations
+
+A complete backlog-authoring task usually leaves:
+
+- one new GitHub Issue with appropriate labels
+- an issue body that is traceable to actual repository evidence
+
+## Example Uses
+
+- "Create a backlog item for adding `--environment` filter to `quality runs coverage`."
+- "Analyze the auto-issue dedup flow and write a backlog item for the missing close-on-pass behavior."
+- "Turn this rough feature request (per-target prompt overrides) into a proper feature backlog item."
+- "Enrich auto-issue #73 (quality-studio:auto) with codebase analysis and fix direction."
+
+---
+
+## Simplicity Standard
+
+See [`../.shared/simplicity-principals.md`](../.shared/simplicity-principals.md) for the full specification.
+
+Apply the PR checklist before finalising any output:
+- [ ] Can a new dev explain this flow in **< 60 seconds**?
+- [ ] Did this add a new concept? If yes, it must be justified.
+- [ ] Can this be deleted later easily?
+- [ ] Are errors observable in one place?