skills.rest
dimagi-internal
dimagi-internalOFFICIAL
Explore all skills by this author →
GitHub

synthetic-walkthrough-spec-qa

Validate walkthrough spec YAMLs with seven static structural contract checks.

1|2|Updated Apr 1, 2026
Search Tags:#zod schema#spec validation#ace plugin#walkthrough qa#auto-fix hints#canopy walkthrough#synthetic specs
One-click install
npx skills add https://github.com/dimagi-internal/ace --skill synthetic-walkthrough-spec-qa
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: synthetic-walkthrough-spec-qa
Source: https://github.com/dimagi-internal/ace/tree/main/skills/synthetic-walkthrough-spec-qa
Command: npx skills add https://github.com/dimagi-internal/ace --skill synthetic-walkthrough-spec-qa

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires yaml, zod, and includes scripts (resource) components.

What problem does it solve?

Running full headless browser walkthroughs to validate spec structure is slow and costly, as failures are only discovered after a complete runtime. This Skill provides fast, static structural QA for per-persona walkthrough specs, catching malformed definitions early to avoid wasted compute and enable quick auto-fix loops.

Core Features & Use Cases

  • 7 Static Zod-Based Checks: Validates YAML parseability, required top-level key presence, scene array structure (minimum 4 well-formed scenes), scene persona resolvability, falsifiable AI quality assertions, documented persona intros, and unique scene titles aligned to the upstream canopy walkthrough spec contract.
  • Fast Failure with Auto-Fix Hints: All checks run in under 100ms with no LLM calls, returning structured auto-fix guidance for each failure so the orchestrator can automatically regenerate specs without manual intervention.
  • Use Case: If you are generating walkthrough specs for Connect opportunities as part of the ACE lifecycle, run this QA immediately after spec generation to catch structural errors before passing specs to the walkthrough runner, reducing iteration time from minutes to milliseconds.

Quick Start

Run the synthetic-walkthrough-spec-qa skill on the generated per-persona walkthrough spec YAML file to receive a binary pass/fail verdict and actionable auto-fix hints for any detected structural issues.

Frequently Asked Questions about synthetic-walkthrough-spec-qa

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I validate walkthrough spec YAML files before running headless browser tests?▼

Validating walkthrough spec YAML files statically with Zod schema checks catches malformed definitions before slow browser runs. This structural QA tool performs 7 specific contract checks on per-persona specs, returning binary pass/fail verdicts with auto-fix hints without executing runtime tests.

What is structural QA for synthetic walkthrough specs and when do I need it?▼

Structural QA for synthetic walkthrough specs is a static validation process checking YAML parseability, scene structure, and persona resolvability. You need it after generating per-persona specs to catch structural errors early, reducing iteration time from minutes to milliseconds and avoiding wasted compute.

Can I use Zod schema validation to check canopy walkthrough spec contracts automatically?▼

Yes, Zod schema validation checks canopy walkthrough spec contracts by verifying required top-level keys, falsifiable AI quality assertions, and unique scene titles. It runs in under 100ms without LLM calls, enabling orchestrator-driven auto-regeneration loops for malformed specs without manual intervention.

Why does my headless walkthrough runner fail on malformed YAML scene definitions?▼

Headless walkthrough runners fail on malformed YAML scene definitions because missing top-level keys, unresolved personas, or non-unique scene titles violate the spec contract. Running static structural QA checks before the runner catches these formatting errors and provides auto-fix hints to correct them.

What's the best way to auto-fix structural errors in per-persona walkthrough specs?▼

The best way to auto-fix structural errors in per-persona walkthrough specs is running static Zod-based QA checks that return structured auto-fix guidance. This enables orchestrator-driven auto-regeneration loops, allowing automated spec correction without manual intervention or LLM calls.

Do I need a minimum number of scenes for valid walkthrough spec YAML?▼

Yes, valid walkthrough spec YAML requires a minimum of 4 well-formed scenes in the scene array structure. Static QA checks enforce this minimum threshold along with other structural requirements like persona resolvability and documented persona intros to ensure spec validity.

Related Skills

Explore More Product & Management Skills→
dimagi-internaldimagi-internal
1

synthetic-walkthrough-spec-eval

Grade per-persona walkthrough specification YAML files across six weighted dimensions.

Official
Advanced
dimagi-internaldimagi-internal
1

synthetic-narrative-plan-qa

Validate synthetic narrative plan YAML manifests with static Zod-based checks.

Official
Advanced
dimagi-internaldimagi-internal
1

synthetic-walkthrough-run

Orchestrate synthetic user walkthroughs for multiple personas and generate scored HTML decks.

Official
Advanced
arthur0narthur0n
8

godot-runtime-smoke

Assert runtime gameplay behavior in headless Godot scenes.

Community
Advanced