/skill-writer

Case Study: Workflow/Process Skill Synthesis

Scenario

Goal: create a skill for repeatable operational workflows (for example PR prep, CI triage, branching, settings audit).

Input collection approach

This case collected process truth from all authoritative locations:

1. Official tool docs and syntax references.
2. Repository workflow conventions and policy docs.
3. Existing local skills with adjacent process logic.
4. CI logs, failure patterns, and known operational pitfalls.
5. Positive and negative historical examples from prior runs.

Collection stopped only after failure and recovery paths were well represented.

Coverage matrix used

Required dimensions tracked during synthesis:

1. Preconditions and required context.
2. Ordered execution flow.
3. Safety/permission boundaries.
4. Expected outputs and acceptance checks.
5. Failure handling and retry behavior.
6. Escalation and handoff behavior.

Synthesized artifacts produced

The resulting skill references included:

1. Happy-path execution transcript.
2. Guarded variant with stricter safety constraints.
3. Failure-recovery transcript for a critical broken step.
4. Output template for deterministic reporting.
5. Changelog rules for iterative improvement from examples.

Source-to-decision trace (sample)

1. Source class: repo policy docs. Decision: add explicit precondition checks before running side-effecting steps. Why: prevented invalid execution in partially configured environments.
2. Source class: CI failure logs. Decision: add a mandatory failure triage branch with retry vs escalate criteria. Why: reduced dead-end loops during workflow execution.
3. Source class: historical positive/negative examples. Decision: standardize output format for easier review and iteration. Why: made regressions and improvements comparable across runs.

Concrete artifacts (sample)

1. Happy-path transcript snippet: Preconditions pass -> execute steps 1..N -> emit structured summary with status per step.
2. Failure-recovery transcript snippet: Step fails -> classify transient/permanent -> retry once or escalate with captured evidence.
3. Deterministic report template: Sections: Preconditions, Actions Taken, Validation Results, Failures/Recoveries, Next Actions.

What made this high quality

1. The workflow was executable without rediscovering steps.
2. Non-happy paths were first-class, not afterthoughts.
3. Outputs were structured for consistent review and iteration.