CawPlan TestRail Link — T2-A8 Manual Mapping Backlink
cawplan skill check
Hard Gates (MUST)
- preview-first → Confirmation Gate →
execute --confirm; tripping the gate is forbidden.
- Workflow B Prerequisite：
milestone mapping-get → has_mapping=false must stop(fixed text see link-plans.md §MilestoneGate); must not continue preview/execute.
- Workflow A Conflict：
conflicts non-empty → execute forbidden; the TestRail/CawPlan side conflict must be handled manually first.
- Forbidden: direct connection to TestRail API; calling
import/execute or plan/execute to impersonate link; execute。
- User display：
ux.md §Glossary；preview_id/mapping_id/UUID hidden by default;Case / Plan / Run / Suite ID must be clickable（ux.md §TestRailLinks）。
- Hot Relay + AutoScan (Workflow A): P1 may skip A1;
suites.length===1 seamless adoption Suite; Section goes through link-cases.md §AutoScan(no parent preview → seamless retry 1 time → only if still failing, prompt A3s).Forbiddento prompt 3.5 "create new top-level / narrow down" each round.
- Cost: lazily load references per
ux.md §Cost , cache mappings get, display preview table truncated; forbidden to repeatedly do full sections listfor disambiguation (during AutoScan retry, allowed to call once per suite cache).
Reference Loading (MUST · Cost Reduction)
| Timing |
Read |
Forbidden |
| Routing / Prompt 0 / Confirmation Gate / Preview·Result Template / Errors |
ux.md corresponds to § |
One-time Read of all references |
| Workflow A only |
link-cases.md corresponds to § |
Read when not routed to A |
| Workflow B only |
link-plans.md corresponds to § |
Read when not routed to B |
Prompt Routing (Prompt 0)
| Hit |
Workflow |
| Test case / Case / CSV / refs / backlink after import / link case |
A |
| Plan / Run / test plan / ticket binding / link plan |
B |
| A and B both hit |
AskUserQuestion choose one of the two (ux.md §Prompts Prompt 0) |
| Neither hit |
Prompt 0: link test case or plan/run？ |
After routing, only one Workflow; forbidden to run A+B mixed in the same round.
Allowed Commands
| Purpose |
Command |
| Mapping / origin |
qa-insights testrail mappings get <product_id> |
| Section lookup (A · AutoScan / Prompt A3s) |
qa-insights testrail sections list <product_id> <suite_id> [--refresh] |
| Milestone gate (B · Step 1) |
qa-insights testrail milestone mapping-get <product_id> <version_id> |
| URL parsing (B · optional) |
qa-insights testrail resolve-url <product_id> --url <url> |
| A preview / execute |
qa-insights testrail link cases preview … · … link cases execute … --preview-id … --confirm |
| B preview / execute |
qa-insights testrail link plans preview … · … link plans execute … --preview-id … --confirm [--supersede] |
| Auxiliary parsing |
products list、versions list、requirements get、testpoints list(only when context is missing) |
Forbidden：cawplan api, chained &&, direct connection to TestRail.
Workflow A — Link Cases (CSV refs backlink)
| Step |
Action |
Detail |
| 0 |
Agent self-checks CSV import prerequisites |
Do not Ask separately; same-session A3 / user says "already imported" → assume satisfied; guide again only when all previews fail |
| 1 |
Parse product_id、requirement_id |
hot relay may skip A1; if missing then ux.md §Prompts Prompt A1 |
| 2 |
mappings get；§AutoSuite |
link-cases.md §Mappings · §AutoSuite |
| 3 |
§AutoScan(first without parent_section_id preview） |
seamless retry ≤1 time; still failing → Prompt A3s |
| 4 |
Show preview (with hyperlink) |
ux.md §PreviewCases；conflict>0 → Stop |
| 5 |
Confirmation gate(only to_link>0） |
to_link=0 → no popup;already_linked>0 and all skipped → success message |
| 6 |
link cases execute --confirm |
ux.md §ResultCases |
Step 3–4 merged execution: AutoScan's first failure preview not shown to user, directly retry or enter A3s.
Workflow B — Link Plans (manual Plan/Run bound to Ticket)
| Step |
Action |
Detail |
| 0 |
Parse product_id、version_id |
if missing then ux.md §Prompts box B1 |
| 1 |
milestone mapping-get |
has_mapping=false → link-plans.md §MilestoneGate, stop |
| 2 |
Collect bindings: Ticket + TestRail Plan/Run URL or ID |
link-plans.md §CollectBindings · box B2 |
| 3 |
Assemble bindings[]；plan_id=0 = Run-only |
link-plans.md §BindingRules |
| 4 |
link plans preview |
link-plans.md §PreviewCLI |
| 5 |
Show preview (with hyperlink) |
ux.md §PreviewPlans；supersede_required>0 → box B-supersede |
| 6 |
Confirmation gate |
ux.md §Prompts box B-confirm |
| 7 |
link plans execute --confirm(when replacing add --supersede） |
ux.md §ResultPlans |
Error (Agent)
| code |
Workflow |
Handle |
MILESTONE_NOT_BOUND |
B |
link-plans.md §MilestoneGate; guide cawplan-testplan-layout |
CONFLICT_BLOCKS_EXECUTE |
A |
column conflicts（ux.md §ConflictMessages); stop |
SUPERSEDE_REQUIRED |
B |
box B-supersede; supplement --supersede |
REQUIREMENT_NOT_FOUND / TICKET_NOT_IN_VERSION |
A/B |
ux.md §Errors |
SUITE_NOT_IN_PROJECT / SECTION_* |
A |
rerun box A3 / box A3s |
PLAN_NOT_FOUND / RUN_NOT_FOUND / RUN_NOT_IN_PLAN |
B |
verify URL/ID;link-plans.md §CollectBindings |
PREVIEW_EXPIRED |
A/B |
preview again (confirmation state can be reused) |
TESTRAIL_UNAVAILABLE |
A/B |
do not execute again |
CONFIRMATION_REQUIRED |
A/B |
supplement --confirm |
auth/403 |
A/B |
ux.md §Errors |
Workflow A conflict message quick reference(BE original text → see ux.md §ConflictMessages）：
TestRail case is already mapped to a different test point — same Case already bound to other test pointTestRail case does not match the case already mapped for this test point — same test point already mapped to other Caseanother TestRail case in this preview claims the same test point and case identity — this preview has duplicate refs
References
- ux.md — routing, Ask box, TestRail hyperlink, Preview/Result template, cost reduction, errors
- link-cases.md — Workflow A: MatchingRules, AutoScan, CLI, preview fields
- link-plans.md — Workflow B: Milestone gate, bindings collection, Run-only, supersede
