cawplan-testcase-import

CawPlan TestCase Import — A1 case import to TestRail

cawplan skill check

Hard gate (MUST)

1. preview-first → Box 4 execution gate → execute --confirm; tripping is prohibited.
2. Data source: already expanded cases → INLINE; test points only → REQUIREMENT. Prohibited source.type=VERSION。
3. Suite / Section confirmation gate：mappings get after Box 3 (Suite) → Box 3.5 (Section attribution)(fixed order) must be confirmed by the user before preview / convert. Prohibited to silently use default_suite_id(no recommendation annotation) or silently reuse/infer parent_section_id。SUITE_NOT_IN_PROJECT/SECTION_NOT_IN_SUITE/SECTION_NOT_FOUND → stop. Already confirmed in the same session and Suite/Section unchanged → may reuse (import-rules §ConfirmState). Box 3.5 ask on every import, exempt from prompting only when Intent explicitly hits or ConfirmState reuses.Version fully transparent: no popup, no inferred confirmation; write only when Intent explicitly hits or the case carries its own value, otherwise do not pass it (note "version unspecified" in the result).
4. User display：ux.md §Glossary；preview_id/job_id/UUID hidden by default; follow the user's primary language; Agent on its own AskUserQuestion(not written into allowed-tools）。
5. TestRail hyperlink：§Preview/§Result/§AsyncHandoff Suite ID, Section ID, Case ID in mustbe clickable and navigable (ux §TestRailLinks); bare numeric IDs prohibited.
6. Hot handoff: P1/P1b → automatic INLINE, skip Box 0, Box 1 (ux.md §Trigger）；do not skip Step 0.6 §StepsCheck；do not skipBox 3, Box 3.5 (unless ux §Intent explicitly hits Suite/Section, or §ConfirmState reuses); Version is transparent and not involved in skip decisions.
7. INLINE body assembly: when data comes from the same session's cawplan-testcase-generate , prohibited to hand-write a camelCase→snake_case conversion script or manually compute source_case_key/priorityitem by item——must first produce an interim JSON isomorphic to A3 csv-template-mapping.md (camelCase, copy fields verbatim, no mapping),after Box 3/3.5 confirmationthen use scripts/convert_generate_to_import.js to convert to body (import-rules.md §Convert）。convert when individual cases steps/expected fail due to non-compliance, the Agent may read <out>.errors.json、after obtaining user consentremove the corresponding entire case from the interim JSON and rerun (delete the entry only, do not change content values); this does not fall under the "manually computing fields" prohibited here.
8. Async Job（to_create > 50）：execute after success default prohibited jobs poll; must first go through ux §AsyncHandoff + Box 6. Only when the user explicitly selects "wait until complete" does it enter the Box 6b wait loop. Job RUNNING when prohibited to repeat execute。
9. After failure, side effects must be verified before retry：execute(sync or async) after being judged failed (known error code or unknown error code),prohibitedto directly reuse the old preview_id or immediately open a new preview and re- execute——the failure may be only a batch-level judgment,execute may have already produced real side effects internally (e.g., Section already created in TestRail). Must first verify according to import-rules §RetrySafety , then decide the next step.
10. Step gate (§StepsCheck): Step 0.6 determines whether the data source isall in title state(0 expanded). All titles → Box Steps-confirm(not a forced stop; optionally "do not expand, continue import");≥1 expanded → seamlessly enter Step 1. Before the user has selected "continue import" and has not changed the data source, prohibit mappings get / preview / execute. It is recommended to first go to A3 to expand; guidance script only(including /cawplan-testcase-generate），prohibit Read cawplan-testcase-generate Skill, prohibit automatically expanding on behalf of the user.

Reference loading (MUST)

Timing	Read	prohibit
Interaction / routing / Preview / report / error / async	ux.md corresponds to §	Read all references at once
body fields / conversion / CLI / BE gaps / async / confirmation state / step gating	import-rules.md corresponds to §	—

prohibit: directly connecting to the TestRail API, holding the TestRail Key, skipping preview.

Allowed commands

Purpose	Command
Mapping	qa-insights testrail mappings get <product_id>
Section lookup (used when box 3.5 looks up by name)	qa-insights testrail sections list <product_id> <suite_id> [--refresh]
Create new Suite (used for box 3 "new" branch)	qa-insights testrail suite-create <product_id> --name <name>
Refresh Requirement	api GET .../qa/requirements/<id>、.../testpoints(REQUIREMENT source only)
INLINE conversion (same-session A3 test cases)	node scripts/convert_generate_to_import.js <interim_json> --suite-id <n> [--version-name "x.x.x"] [-o <out.json>]
Preview	qa-insights testrail import preview <product_id>
Execute	qa-insights testrail import execute <product_id> --preview-id <id> --confirm
Async	jobs get(default, check progress) · jobs poll(only when the user explicitly requests waiting until completion and accepts a long block)

Workflow

Step	Action	Detail
0	Parse product_id, data source,source.type	ux §Trigger · ux §Intent · import-rules §数据源
0.5	missing context → box 0/1	ux §Prompts
0.6	§StepsCheck: all-title state → box Steps-confirm; ≥1 expanded → seamlessly next step	import-rules §StepsCheck · ux §StepsConfirm · P1/P1b still mustthis step
1	mappings get; record suites[]、default_suite_id、testrail_origin	import-rules §Suite · ux §TestRailLinks
1.5	box 3 Suite → box 3.5 Section ownership(if "existing" is selected,sections list match) (fixed order; reusable §ConfirmState）	ux §SuiteConfirm · ux §SectionConfirm · before convert/preview
2	assemble body (INLINE + A3 → interim JSON → convert use the confirmed suite_id/parent_section_id，version_name if Intent matches or the test case carries it, include it together)	import-rules §body · §Convert · §Section · §Version
3	import preview；ux §Preview header includes Suite+version; store preview_id	to_fail>0 → box 5, stop
4	box 4 execution gate (duplicate Suite+version)	ux §Prompts · to_create>50 → ux §AsyncEstimate
5	import execute --confirm	sync → Step 7;job_id → Step 6a
6a	async delivery (default)	ux §AsyncHandoff · box 6 · import-rules §AsyncJob
6b	wait until completion (optional)	jobs get loop · ux §AsyncProgress · ux §AsyncTimeout
7	import report	ux §Result

T1 handoff: same-session cawplan-testcase-generate → this Skill (INLINE). First Step 0.6(if all titles then Steps-confirm; if the user selects continue or there are no steps then enter Step 1) → write interim JSON → box 3/3.5 confirmation → convert_generate_to_import.js → preview. Direct Requirement import (client has no steps) is treated as all-titles at Step 0.6 and goes through the same Steps-confirm.

Change Suite / change Section ownership: the user says change Suite/Section → clear the corresponding §ConfirmState → redo box 3 (also clear Section) or box 3.5 → a new preview is required.Change version: User mentions a new version → update directly confirmed_version_name(no popup needed) → new preview required.

Asynchronous continuation: In the same session, "check import status" → jobs get（ux §Intent); must be already saved job_id + product_id。

Error (Agent)

code	Handling
TESTRAIL_UNAVAILABLE	ux §Errors; do not repeat execute
PREVIEW_EXPIRED	Preview again (if Suite/version is still valid, reuse §ConfirmState）
SUITE_NOT_IN_PROJECT	ux §Errors; stop
SECTION_NOT_IN_SUITE / SECTION_NOT_FOUND	ux §Errors; go through box 3.5 again
SUITE_CREATE_RATE_LIMITED / SUITE_MODE_NOT_SUPPORTED	ux §Errors; switch to box 3 "existing" branch
validation / missing source.type	fix it yourself; do not expose to the user
auth/403	ux §Errors
UNKNOWN(Job timeout)	jobs get reconciliation · ux §AsyncTimeout
CONFIRMATION_REQUIRED	supplement --confirm
Job RUNNING(check status after 6a)	jobs get → ux §AsyncProgress; do not repeat execute
execute returns failed === to_create and failed_cases[].error single	import-rules §Diagnosis; most likely a systemic problem rather than a problem with this batch of data; first go through §RetrySafety, do not guide "change the data and retry"
unknown code not in this table	ux §UnknownError; stop, do not retry without authorization; organize product_id/preview_id/job_id/error code/failed_cases sample for the user to decide whether to report

References

• ux.md — friendly name, routing, Suite/Section confirmation, version-transparent rules, Preview, async, reporting, errors, unknown-error fallback
• import-rules.md — data source, Suite/Section/Version, ConfirmState, body, Convert, CLI, async Job, failure signal identification, side-effect verification before retry, BE gaps