case-data-material-planner
One-stop material engine between case authoring and case execution.
- Build an optional business-context graph from requirements
- Parse entities and actions from each case
- Construct data and bind commands through adapters
- Emit
case-executable.md
How the work is divided
scripts/pipeline.ts owns orchestration. You supply judgment at three points
only — parse-case, knowledge-build, and select-tool — and the script does
construction, binding, linting, and writeback. This split exists because those
three stages need reading comprehension while the rest must be reproducible: a
case re-run tomorrow has to yield the same manifest, which is impossible if a
model re-derives each step. So when the runner exits asking for one of the three,
launch that Agent, merge its patch, and --resume; do not take over a stage the
script already implements (invoke_entity.ts, bind_action.ts,
slot_render.ts), and with 2+ cases go through the dispatcher so each case gets
its own pipeline.ts process.
Hard constraints
These are the ones that silently corrupt output rather than failing loudly,
which is why they are worth stating:
- Do not invent business IDs, amounts, or config values. A plausible-looking
ID makes a case that fails at execution time with no trace of where the value
came from. When unsure, record
failReason and let the gate surface it.
- Parse before constructing. Data needs come from the case's preconditions
and steps; skipping parse means constructing something the case never asked
for.
- Keep
case-executable.md business-only. No node / python / bash
invoke lines, no skillRoot, cwd, host, or mock-server ports — those live in
manifest.json (invokeCmd / filledCmd). The case document is read by
people and replayed in other environments, where local paths and ports are
wrong or meaningless.
- Persist every non-envelope business field, not just the primary ID. A
downstream step usually needs the attributes that came back with it, and
re-fetching them is not always possible.
- Respect the gates. C3 stays blocking when lint-gate is abnormal, and the
lint-gate loop runs at most 3 rounds before it must hand the decision to the
user — an unbounded loop burns the run without converging.
- During knowledge-build, describe the business, not a shopping list. The
graph answers "what does this domain look like"; deciding what data to prepare
is the parse stage's job and doing it early biases the parse.
Entry routes
After receiving the request, classify the input:
Path A: requirement / design doc (+ cases)
- Read
planner.md and run scripts/pipeline.ts
- Exit 12 → knowledge-build Agent, merge,
--resume
- Then parse (exit 11) or continue if cases were already parsed
Path B: cases only (no requirement doc)
- Read
planner.md and run scripts/pipeline.ts --case-id … --source …
- Reuse
./testdata/case-materials/business-context.json via --context when it exists
- Otherwise knowledge-build is skipped by the runner
- Handle exit 11 (parse-case) then
--resume. Construction, binding, and
writeback stay inside pipeline.ts — do not take those stages over.
Path C: batch (2+ cases)
When the user supplies 2 or more cases:
- Read
case-dispatcher.md and follow it
- One
pipeline.ts process per case (parallel). Shared knowledge-build once
- The user talks to the dispatcher, not a per-case Planner Agent
Rule:
- case count ≥ 2 → Path C
- case count == 1 → Path A or B
Input sources (highest first)
| Priority |
Source |
How |
Notes |
| 0 |
Caller-supplied sources[] |
Passed in the Task / delegate prompt |
Each item is {caseId, sourceType, sourcePath}; skip interactive collection |
| 1 |
Document URL |
doc_source.get(<ref>) |
Requirement / design / knowledge-base page |
| 2 |
planId |
workspace_context.get_plan(<id>) + api_catalog.search_plan_changes(<id>) |
Plan detail and change APIs |
| 3 |
Local file path |
Read the file |
|
| 4 |
Pasted text |
Use as-is |
|
Priority 0 is an optional fast path. sourceType values:
remote-case | local-file | planId | paste.
They map to the four legal caseSource.type values.
Callers that omit sources[] still use priorities 1–4 interactively.
Material gate (case source)
The prerequisite material is the case pack, not executor fields.
- No case source → ask for a file, paste,
planId, or document URL. Do not invent case text. Do not start parse or construct.
- Path A without cases → finish knowledge-build, then wait for cases. Do not jump to invoke.
- Path B → at least one case is mandatory.
knowledge-build may be skipped; parse may not.
- Batch (2+) → every listed case needs a resolvable source. Do not silently drop a case.
- After the user supplies cases,
--resume pipeline.ts. Do not skip parse, invoke, or writeback.
- Executor / tool params inside pipelines follow the original fill rules (defaults for optional fields; do not invent core IDs). C3 / lint-gate stay blocking.
Constraints
- Execution logic lives in
scripts/pipeline.ts; planner.md is the host protocol
- LLM Agents allowed:
parse-case, knowledge-build, select-tool only
- Do not skip C3; the happy path has zero human gates
- Lint-gate loop is at most 3 rounds
- Entities and actions are equal tracks; an empty track short-circuits
targetLocation is the only bind to the original case text
- Action params:
paramsFromEntities / paramsFromGenerators / paramsFromPriorActions
- Tool verify uses
tool_registry.query_input_list (see references/param-source-spec.md)
businessContext = null is a valid degraded mode
- Entities follow
constructionStrategy: tool-build → invoke_entity.ts,
config → generate_config_commands.ts, static-value → filled at parse,
runtime → deferred to execution
- New scenes: drop a slot under pack
slots/ or workspace.slot_roots.
select_tool.ts binds from slot.yaml (or inferred executors). Do not edit the selector
Path roots
Two roots, and mixing them up is the most common failure here:
| Variable |
Points at |
Owns |
SUBSKILL_DIR |
directory of this file ($SKILL_DIR/references/case-data-material-planner/) |
scripts/, agents/, templates/, references/ — every relative path in this sub-skill |
SKILL_DIR |
the parent skill root that contains the top-level SKILL.md |
scripts/adapters/, scripts/search_data_build.ts, slots/ |
There is no adapters/ folder under SUBSKILL_DIR/scripts/. Adapter calls go to
$SKILL_DIR/scripts/adapters/cli.ts.
File layout
SKILL.md entry routing (this file)
planner.md host protocol for pipeline.ts
case-dispatcher.md multi-case: one pipeline.ts per case
agents/ LLM specs (parse / knowledge-build / select-tool)
knowledge-build.md
parse-case.md
select-tool.md
writeback.md slot_render render rules, applied by the script
scripts/ pipeline.ts + construct/writeback scripts
templates/ manifest / cache / context templates
references/ thresholds and contracts
Outputs
./testdata/case-materials/business-context.json
./testdata/case-materials/tool-binding-cache.json
./testdata/case-materials/{case-id}/manifest.json
./testdata/case-materials/{case-id}/case-executable.md
Dependencies
No private CLIs. All I/O goes through the parent skill's adapters
($SKILL_DIR/scripts/adapters/cli.ts):
| Need |
Adapter |
| Discover / install domain skills |
skill_marketplace |
| Query / execute / publish tools |
tool_registry |
| Discover HTTP APIs |
api_catalog |
| Proven methods |
experience_store |
| Documents |
doc_source |
| Test-plan context |
workspace_context |
| Case writeback |
case_writeback |
| Config and SQL |
config_store, data_store |
Collaboration
This sub-skill is hosted by codexqa-testdata-generator. select_tool.ts reuses
scripts/parallel_search.ts, which calls the same adapters. Enterprise tools
are added through those adapters or a new slot under slots/ /
workspace.slot_roots — invoke_entity.ts only dispatches on toolType.
1---2name: case-data-material-planner-23description: >-4 Prepares executable case preconditions and case-executable.md from a5 requirement or written cases. Internal case-material engine; enter6 through codexqa-testdata-generator so SKILL_DIR and adapters resolve.7license: Apache-2.08metadata:9 source: https://skillmd.com/skills/openqa-cn/case-data-material-planner-210---1112# case-data-material-planner1314One-stop material engine between case authoring and case execution.1516- Build an optional business-context graph from requirements17- Parse entities and actions from each case18- Construct data and bind commands through adapters19- Emit `case-executable.md`2021## How the work is divided2223`scripts/pipeline.ts` owns orchestration. You supply judgment at three points24only — `parse-case`, `knowledge-build`, and `select-tool` — and the script does25construction, binding, linting, and writeback. This split exists because those26three stages need reading comprehension while the rest must be reproducible: a27case re-run tomorrow has to yield the same manifest, which is impossible if a28model re-derives each step. So when the runner exits asking for one of the three,29launch that Agent, merge its patch, and `--resume`; do not take over a stage the30script already implements (`invoke_entity.ts`, `bind_action.ts`,31`slot_render.ts`), and with 2+ cases go through the dispatcher so each case gets32its own `pipeline.ts` process.3334## Hard constraints3536These are the ones that silently corrupt output rather than failing loudly,37which is why they are worth stating:3839- **Do not invent business IDs, amounts, or config values.** A plausible-looking40 ID makes a case that fails at execution time with no trace of where the value41 came from. When unsure, record `failReason` and let the gate surface it.42- **Parse before constructing.** Data needs come from the case's preconditions43 and steps; skipping parse means constructing something the case never asked44 for.45- **Keep `case-executable.md` business-only.** No `node` / `python` / `bash`46 invoke lines, no `skillRoot`, cwd, host, or mock-server ports — those live in47 `manifest.json` (`invokeCmd` / `filledCmd`). The case document is read by48 people and replayed in other environments, where local paths and ports are49 wrong or meaningless.50- **Persist every non-envelope business field**, not just the primary ID. A51 downstream step usually needs the attributes that came back with it, and52 re-fetching them is not always possible.53- **Respect the gates.** C3 stays blocking when lint-gate is abnormal, and the54 lint-gate loop runs at most 3 rounds before it must hand the decision to the55 user — an unbounded loop burns the run without converging.56- **During knowledge-build, describe the business, not a shopping list.** The57 graph answers "what does this domain look like"; deciding what data to prepare58 is the parse stage's job and doing it early biases the parse.5960---6162## Entry routes6364After receiving the request, classify the input:6566### Path A: requirement / design doc (+ cases)67681. Read `planner.md` and run `scripts/pipeline.ts`692. Exit 12 → knowledge-build Agent, merge, `--resume`703. Then parse (exit 11) or continue if cases were already parsed7172### Path B: cases only (no requirement doc)73741. Read `planner.md` and run `scripts/pipeline.ts --case-id … --source …`752. Reuse `./testdata/case-materials/business-context.json` via `--context` when it exists763. Otherwise knowledge-build is skipped by the runner774. Handle exit 11 (parse-case) then `--resume`. Construction, binding, and78 writeback stay inside `pipeline.ts` — do not take those stages over.7980### Path C: batch (2+ cases)8182When the user supplies **2 or more cases**:83841. Read `case-dispatcher.md` and follow it852. One `pipeline.ts` process per case (parallel). Shared knowledge-build once863. The user talks to the dispatcher, not a per-case Planner Agent8788**Rule:**8990- case count ≥ 2 → Path C91- case count == 1 → Path A or B9293### Input sources (highest first)9495| Priority | Source | How | Notes |96|---|---|---|---|97| 0 | Caller-supplied `sources[]` | Passed in the Task / delegate prompt | Each item is `{caseId, sourceType, sourcePath}`; skip interactive collection |98| 1 | Document URL | `doc_source.get(<ref>)` | Requirement / design / knowledge-base page |99| 2 | `planId` | `workspace_context.get_plan(<id>)` + `api_catalog.search_plan_changes(<id>)` | Plan detail and change APIs |100| 3 | Local file path | Read the file | |101| 4 | Pasted text | Use as-is | |102103Priority 0 is an optional fast path. `sourceType` values:104`remote-case | local-file | planId | paste`.105They map to the four legal `caseSource.type` values.106Callers that omit `sources[]` still use priorities 1–4 interactively.107108## Material gate (case source)109110The prerequisite material is **the case pack**, not executor fields.111112- **No case source** → ask for a file, paste, `planId`, or document URL. Do not invent case text. Do not start parse or construct.113- **Path A without cases** → finish knowledge-build, then **wait** for cases. Do not jump to invoke.114- **Path B** → at least one case is mandatory. `knowledge-build` may be skipped; parse may not.115- **Batch (2+)** → every listed case needs a resolvable source. Do not silently drop a case.116- After the user supplies cases, `--resume` `pipeline.ts`. Do not skip parse, invoke, or writeback.117- Executor / tool params inside pipelines follow the original fill rules (defaults for optional fields; do not invent core IDs). C3 / lint-gate stay blocking.118119---120121## Constraints122123- Execution logic lives in `scripts/pipeline.ts`; `planner.md` is the host protocol124- LLM Agents allowed: `parse-case`, `knowledge-build`, `select-tool` only125- Do not skip C3; the happy path has zero human gates126- Lint-gate loop is at most 3 rounds127- Entities and actions are equal tracks; an empty track short-circuits128- `targetLocation` is the only bind to the original case text129- Action params: `paramsFromEntities` / `paramsFromGenerators` / `paramsFromPriorActions`130- Tool verify uses `tool_registry.query_input_list` (see `references/param-source-spec.md`)131- `businessContext = null` is a valid degraded mode132- Entities follow `constructionStrategy`: `tool-build` → `invoke_entity.ts`,133 `config` → `generate_config_commands.ts`, `static-value` → filled at parse,134 `runtime` → deferred to execution135- New scenes: drop a slot under pack `slots/` or `workspace.slot_roots`.136 `select_tool.ts` binds from `slot.yaml` (or inferred executors). Do not edit the selector137138## Path roots139140Two roots, and mixing them up is the most common failure here:141142| Variable | Points at | Owns |143|---|---|---|144| `SUBSKILL_DIR` | directory of this file (`$SKILL_DIR/references/case-data-material-planner/`) | `scripts/`, `agents/`, `templates/`, `references/` — every relative path in this sub-skill |145| `SKILL_DIR` | the parent skill root that contains the top-level `SKILL.md` | `scripts/adapters/`, `scripts/search_data_build.ts`, `slots/` |146147There is no `adapters/` folder under `SUBSKILL_DIR/scripts/`. Adapter calls go to148`$SKILL_DIR/scripts/adapters/cli.ts`.149150## File layout151152```153SKILL.md entry routing (this file)154planner.md host protocol for pipeline.ts155case-dispatcher.md multi-case: one pipeline.ts per case156agents/ LLM specs (parse / knowledge-build / select-tool)157 knowledge-build.md158 parse-case.md159 select-tool.md160 writeback.md slot_render render rules, applied by the script161scripts/ pipeline.ts + construct/writeback scripts162templates/ manifest / cache / context templates163references/ thresholds and contracts164```165166## Outputs167168- `./testdata/case-materials/business-context.json`169- `./testdata/case-materials/tool-binding-cache.json`170- `./testdata/case-materials/{case-id}/manifest.json`171- `./testdata/case-materials/{case-id}/case-executable.md`172173## Dependencies174175No private CLIs. All I/O goes through the parent skill's adapters176(`$SKILL_DIR/scripts/adapters/cli.ts`):177178| Need | Adapter |179|---|---|180| Discover / install domain skills | `skill_marketplace` |181| Query / execute / publish tools | `tool_registry` |182| Discover HTTP APIs | `api_catalog` |183| Proven methods | `experience_store` |184| Documents | `doc_source` |185| Test-plan context | `workspace_context` |186| Case writeback | `case_writeback` |187| Config and SQL | `config_store`, `data_store` |188189## Collaboration190191This sub-skill is hosted by `codexqa-testdata-generator`. `select_tool.ts` reuses192`scripts/parallel_search.ts`, which calls the same adapters. Enterprise tools193are added through those adapters or a new slot under `slots/` /194`workspace.slot_roots` — `invoke_entity.ts` only dispatches on `toolType`.