x4-seed

name	x4-seed
description	Create X4 test seeds in YAML under tests/seeds based on user description. Use when the user asks to generate or update a seed file for fixture generation.

X4 Seed

Create or update a seed YAML file in tests/seeds/ for later fixture generation. This skill is meta: the concrete seed schema and contents are defined by the user task. Seeds MUST be generated by a script that reads from src/assets/x4_game_data/8.0-Diplomacy/**. The seed MUST contain only the minimal information needed to generate fixtures. All derivable fields MUST be omitted.

Trigger

User asks to create/update a seed, or mentions seed generation for fixture creation.

Output Rules (MANDATORY)

• Format: YAML.
• Path: tests/seeds/<seed-name>.yaml.
• Script path: scripts/seed/<seed-name>.tsx.
• JSON-to-type mapping (read on execution, no format details here):
  • wares.json -> X4Ware
  • modules.json -> X4Module
  • module_groups.json -> X4ModuleGroup
  • res.json -> X4Resource
  • consumption.json -> X4Consumption
  • languages.json -> X4Language
• Locale name resolution (optional):
  • Only use locale lookup when the user explicitly requests it.
  • Otherwise, the agent may resolve wareId/moduleId via search and write ids directly into the script.
• Only include fields required to generate fixtures; omit derivable fields.
• Include human-reviewable structure and comments when useful.
• Do not generate fixtures in this skill.
• Do not touch tests/fixtures/**.
• Do not hand-author seed content; use a script.
• Use the yaml package from package.json for serialization; do not hand-build YAML strings.

Minimal Field Gate (MANDATORY)

• Before generating any script, confirm the minimal field list with the user.
• If the user has not explicitly confirmed the minimal fields, stop and ask.
• Always echo the final minimal field list before writing the script.
• Require an explicit user confirmation (e.g. “confirm minimal fields”) before script creation.

Minimal Field Template (MANDATORY)

Use this template to confirm scope; remove items the user says are not needed.

• plan: name
• group: name, category, subCategory, isLocked, lockedLineage
• node: moduleId | wareId, isIsolated

Ambiguous Field Ownership (MANDATORY)

• If there is any uncertainty about which level owns a field (plan/group/node), stop and ask.

Store Resolution (MANDATORY)

• Derive the target store (e.g. logic-flow vs empire) from the user's stated purpose.
• If the store is ambiguous, ask explicitly before generating the script.
• After resolution, print: Resolved store: <store>.

Workflow (MANDATORY)

1. Clarify seed name, target scope, and minimal schema from the user request.
2. Read src/types/x4.ts to understand the JSON type structures listed above.
3. Resolve ids for requested items (via search) and write ids directly into the script unless locale lookup is explicitly requested.
4. Write a script at scripts/seed/<seed-name>.tsx that reads src/assets/x4_game_data/8.0-Diplomacy/** JSON and generates the seed.
5. Run the script by default (after requirements are fully clarified) to produce tests/seeds/<seed-name>.yaml, and show the generated content in output while writing the file.
6. Provide a brief summary of what the seed covers and what is intentionally omitted.

Execution (DEFAULT + FALLBACK)

• Default: npx tsx scripts/seed/<seed-name>.tsx
• Fallback when tsx is unavailable or blocked:
  1. npx tsc --target ES2022 --module NodeNext --moduleResolution NodeNext --outDir .tmp/seed-compile scripts/seed/<seed-name>.tsx
  2. node .tmp/seed-compile/<seed-name>.js

YAML Comment Policy

• YAML may include # comments.
• Comments should document intent or mapping notes for reviewers.
• Do not include verbose commentary.

Constraints

• No source code edits.
• No fixture generation.
• Keep seed content strictly tied to the current request.
• The script must be specific to the current task and may assume the minimal schema defined by the user request.

Output

• Created/updated seed file path.
• Summary of included fields.
• Any open questions or ambiguities blocking minimal seed definition.

Lessons Learned

1. Confirm data source before coding

• Counterexample: Assumed Jian's ship ID without searching first
• Correct approach: Query the game data to confirm correct IDs before writing the generation script

2. Design data model for complete data flow

• Counterexample: Added name field to seed but hardcoded name: '' in db_fixture script
• Lesson: When adding new fields, update the entire pipeline (seed → script → fixture → store)

3. Analyze input data structure before complex logic

• Counterexample: Wrote wrong Osaka shield config because didn't understand the slot structure
• Correct approach: Explore the game data structure first, understand slot types and max counts before writing transformation logic

4. Validate user input against business rules

• Counterexample: User said "shield Mk2 x3 + Mk3 x2" but there are only 3 slot groups, wrote it anyway
• Correct approach: User input may be incorrect. Validate against business rules (slot count, max capacity). When conflicts found, propose modifications instead of blindly executing

5. Output verifiable summaries from automation scripts

• Counterexample: Generated seed and fixture multiple times before noticing config errors
• Correct approach: Script should output key configuration summary for quick human verification