Appropriate use
Use during refinement, grooming, design review, or before a developer begins implementation.
Scope and intent
A controlled workflow specification
This page defines the behaviour, controls, evidence, and outputs required from the skill. It does not claim that a language model can enforce security or correctness by wording alone.
Non-goals
Do not use as a substitute for product decisions, legal approval, security threat modelling, or technical design ownership.
- 8
- versioned workflow phases
- 3
- explicit approval gates
- 5
- defined result states
- 8
- versioned output artifacts
Material changes to the source, environment, identity, approved actions, or expected behaviour invalidate dependent approvals and require revalidation.
Workflow
The 8 phases
Each phase has explicit inputs and outputs. Approval gates are hard stops bound to exact versions and hashes.
Phase 1: Source and version preflight Gate 1 · approve source set
Fetch the exact ticket revision, linked designs, API contracts, parent initiatives, dependent tickets, and referenced incidents. Record inaccessible sources instead of guessing.
ticket ID · revision · author · status · links · attachment hashes
Phase 2: Intent extraction
Separate the customer problem, business outcome, proposed solution, acceptance criteria, constraints, assumptions, and explicit exclusions.
problem · actor · desired outcome · proposed behaviour · non-goals
Phase 3: Ambiguity and contradiction analysis
Detect undefined terms, conflicting statements, incomplete branches, missing states, conflicting designs, and mismatches between title, description, acceptance criteria, and comments.
ambiguity · contradiction · stale comment · hidden assumption · unresolved decision
Phase 4: Testability analysis
Check whether every expected behaviour has an observable result, controllable precondition, accessible environment, stable data setup, and measurable success condition.
observable · controllable · repeatable · measurable · isolated
Phase 5: Risk and dependency mapping
Identify roles, permissions, tenants, devices, integrations, migrations, notifications, analytics, accessibility, performance, security, and backward-compatibility impact.
direct dependencies · indirect dependencies · operational risk · customer risk
Phase 6: Question and recommendation drafting
Write concise questions that request concrete decisions. Keep assumptions separate and never silently turn them into requirements.
decision owner · required answer · impact if unanswered · suggested default
Phase 7: Stakeholder review Gate 2 · confirm decisions
Present the findings grouped by blocker, material gap, improvement, and optional clarification. Bind accepted decisions to the ticket revision.
blocking gaps · accepted assumptions · owner · due date
Phase 8: Publish review record Gate 3 · publish review
Generate a ticket-ready summary, testability verdict, traceable decision log, and follow-up checklist. Reopen the review if the ticket changes materially.
idempotent comment · revision hash · unresolved items · change trigger
Approval contract
Every gate approves an exact decision object
An approval cannot be reused after its environment, source, action plan, or approved document changes.
| Gate | Decision | Required binding |
|---|---|---|
| 1 | Gate 1 · approve source set | Approval stores approver, role, timestamp, context hash, approved document hash, expiry, and invalidation state. |
| 2 | Gate 2 · confirm decisions | Approval stores approver, role, timestamp, context hash, approved document hash, expiry, and invalidation state. |
| 3 | Gate 3 · publish review | Approval stores approver, role, timestamp, context hash, approved document hash, expiry, and invalidation state. |
Result model
Defined states prevent vague conclusions
Attempt outcomes remain separate from these workflow results. Errors, cancellations, and invalid context are never silently converted into a pass.
READY
The ticket is sufficiently clear and testable for the agreed scope.
READY WITH ASSUMPTIONS
Work may continue only with explicitly recorded, owned assumptions.
NEEDS CLARIFICATION
Material questions remain but do not yet prove the ticket is invalid.
BLOCKED
A missing decision, source, environment, or dependency prevents responsible implementation or testing.
OUT OF SCOPE
The item is not a product-behaviour ticket or requires another review process.
Evidence contract
Evidence must directly support the claim
Evidence has provenance, capture context, privacy classification, retention, and integrity metadata. A convenient artifact is not automatically sufficient proof.
| Claim | Primary evidence | Required validation |
|---|---|---|
| Requirement statement | Exact ticket excerpt and revision | Quoted text is short, contextual, and traceable to its source. |
| Design expectation | Design frame or specification reference | Frame/version and affected state are identified. |
| API behaviour | Contract or endpoint reference | Schema version, status behaviour, and ownership are explicit. |
| User role | Role and tenant matrix | Actor, ownership, and allowed operation are named. |
| Decision | Approved comment or decision record | Owner, timestamp, chosen option, and revision are recorded. |
| Testability | Observable result mapping | Every acceptance criterion maps to a controllable test and evidence type. |
Trust and safety
Controls that must be enforced outside the prompt
These controls belong in the runtime, connector permissions, sandbox, renderer, storage layer, and review process.
Runtime control
No invented requirements
The skill may suggest options but cannot choose product behaviour without an authorised decision.
Runtime control
Source provenance
Every material statement cites a ticket section, design, contract, or explicit stakeholder decision.
Runtime control
Version invalidation
A material ticket or design update invalidates the prior READY verdict.
Runtime control
Sensitive content handling
Customer names, credentials, private URLs, and attachments follow access and retention policy.
Runtime control
Question quality
Questions request one concrete decision and explain the consequence of leaving it unanswered.
Runtime control
Role separation
The reviewer identifies conflicts but does not impersonate Product, Engineering, Security, or Legal ownership.
Decision policy
Ordered outcomes, not averaged pass counts
The first applicable high-severity outcome takes precedence. A manual override is recorded separately and never rewrites the calculated result.
BLOCKED
A required decision, source, owner, or test mechanism is unavailable.
NEEDS CLARIFICATION
Material ambiguity or contradiction remains.
READY WITH ASSUMPTIONS
Explicit assumptions are approved, owned, and time-bounded.
READY
The reviewed revision is clear, internally consistent, and testable for the agreed scope.
Known limitations
Uncertainty and coverage limits remain visible
The workflow documents what it cannot prove and what further evidence would change confidence.
- Limit 1. Clear requirements can still describe the wrong product decision; this skill reviews quality and testability, not product-market correctness.
- Limit 2. Historical comments may be stale. The latest authorised decision must be identified explicitly.
- Limit 3. Designs and API contracts can diverge; the skill flags the conflict but cannot choose the source of truth.
- Limit 4. Non-functional expectations may need specialist review and measurable service objectives.
- Limit 5. A READY verdict applies only to the reviewed revision and linked source versions.
- Limit 6. Small tickets may use a lightweight mode, but skipped checks must remain visible.
Outputs
Versioned records for review and continuation
Human summaries are generated from validated structured records. They are not maintained as separate, drifting sources of truth.
review-context.jsonVersioned output produced by the workflow.
source-map.mdVersioned output produced by the workflow.
requirement-map.yamlVersioned output produced by the workflow.
gaps.mdVersioned output produced by the workflow.
questions.mdVersioned output produced by the workflow.
decision-log.jsonlVersioned output produced by the workflow.
ticket-comment.mdVersioned output produced by the workflow.
review-report.htmlVersioned output produced by the workflow.
artifacts/qa/ticket-review/<run-id>/ ├── review-context.json ├── source-map.md ├── requirement-map.yaml ├── gaps.md ├── questions.md ├── decision-log.jsonl ├── ticket-comment.md └── review-report.html
Example
Example request and controlled output
Input
Review ticket QA-2201 before refinement. Focus on roles, error handling, analytics, and whether the acceptance criteria are testable.
Output excerpt
Verdict: NEEDS CLARIFICATION Blocking questions: 1. Which roles may edit the configuration after creation? 2. What should the user see when the external service times out? 3. Is analytics expected for both successful and failed submissions? Testability gap: The phrase “loads quickly” has no measurable threshold or target environment.
Production readiness
Required before operational use
The written skill is only one layer. The repository, runtime, connectors, evidence storage, and publication path must implement these requirements.
- Required. Tool, filesystem, repository, command, secret, and network permissions are enforced outside the model.
- Required. Every source, environment, build, plan, and approval has a version or content hash.
- Required. Untrusted values are escaped, length-bounded, path-safe, and separated from executable instructions.
- Required. Attempt outcomes, scenario verdicts, workflow decisions, and publication status remain separate.
- Required. Raw evidence, publishable evidence, access control, retention, redaction, and deletion are defined.
- Required. Concurrent runs use unique IDs, locks, idempotency keys, and conflict-aware updates.
- Required. Material changes invalidate dependent approvals and outcomes.
- Required. The repository validator passes before the skill is considered production-ready.
In one line
/ticket-review
Reviews a Jira or Linear ticket before implementation or QA begins, exposing ambiguity, contradiction, hidden dependencies, missing acceptance criteria, and untestable expectations.