skill-name-kebab-case

Skill Name

Briefly summarize the target task, scope, and expected outcome of this skill.

Gotchas

• Gotcha 1: [Describe a highly specific, non-obvious, environment-dependent pitfall that models are likely to hit, rather than generic advice].
• Gotcha 2: [e.g., database soft-deletes, multi-system field name mapping, or silent health checks].

Workflow Checklist

Progress:

• Step 1: Parse and Inventory (Load references/schema.md or execute scripts/parse.py).
• Step 2: Formulate Plan (Create a plan JSON and validate using scripts/validate.py).
• Step 3: Execute Task (Apply changes with idempotent actions).
• Step 4: Verify Results (Run tests and confirm output formatting).

Detailed Guidelines

Step 1 — Parse & Inventory

Instruct the agent how to analyze the environment:

1. Load references/guidelines.md for specific style rules.
2. Verify input arguments. If ambiguous, reject immediately with clear options.

Step 2 — Validation Loop

Instruct the agent to execute a deterministic loop to prevent broken output:

1. Perform the edit.
2. Validate using a validation script:

   python3 scripts/validate.py "$TARGET_FILE"
   

3. If validation fails:
   • Carefully inspect error codes and diagnostics in stderr.
   • Revise target code/text.
   • Run validation again.
4. Do NOT proceed to the next step until validation completely passes.

Step 3 — Plan-Validate-Execute

For batch, risky, or destructive actions:

1. Extract data structures into a planning file plan.json.
2. Compare plan fields against the schema.
3. Validate:

   python3 scripts/compare_schema.py plan.json references/schema.json
   

4. If valid, proceed with --confirm or --force.

Output Templates

When presenting results, format exactly like this template:

# [Task Title]

## Executive Summary
[Brief description of changes made]

## Applied Checklist
- [x] Change 1
- [x] Change 2

## Recommendations / Next Steps
1. [First actionable step]
2. [Second actionable step]