name: transform-raw-spec description: Transform a raw rules/spec document into a complete, testable specification via Steps 1–7, using curated templates, best examples, and timestamped outputs. license: Apache-2.0 metadata: olaf_tags: [business-analyst, requirements, transformation, EARS, testability, mermaid] copyright: Copyright (c) 2026 pjmp020564 author: pjmp020564 (on github) repository: https://github.com/haal-ai/haal-ide provider: Haal AI
CRITICAL: Ensure OLAF condensed framework is loaded: <olaf-work-instructions>, <olaf-framework-validation>. If not loaded, read ~/reference/.condensed/olaf-framework-condensed.md.
Time Retrieval\s*Get current timestamp in YYYYMMDD-HHmm format
If the above commands don't work, use scripts/now/bin/now-<os>-<arch> with -format "20060102-1504" (Windows: now-windows-amd64.exe).
Input Parameters
- raw_rules_path: string — Path to the source rules/spec (e.g., scripts/olaf/rules.md)
- output_folder: string — Target folder to write step files (e.g., spec-<channel>-<model>)
- spec_name: string — Short name for the spec (used in headings)
- strict_template_compliance: boolean — Enforce templates strictly (default: true)
User Interaction
For each step:
- Propose: Show the planned structure using the template and cite the best example
- Act: Generate the output file using a fresh timestamp (YYYYMMDD-HHMM) and save it under
[output_folder] - Confirm: Summarize what was produced and any open decisions
Global Rules
- Each step file must use its own fresh timestamp (no shared timestamp).
- Timestamp format:
YYYYMMDD-HHMM. - Use templates under
templates/and best examples to guide depth and structure. - Record all user decisions in Steps 3–5 and trigger a Step 2 refresh if flags/terms/policies change.
Templates and Best Examples
- Step 1 template:
templates/step1-clarify-group-template.md- Best example:
spec-github-sonnet4/step1-<timestamp>.md
- Best example:
- Step 2 template:
templates/step2-ears-template.md- Best example:
spec-windsurf-gpt5lr/step2-<timestamp>.md(decision-aligned EARS)
- Best example:
- Step 3 template:
templates/step3-quality-check-template.md- Best example:
spec-windsurf-gpt5lr/step3-<timestamp>.md(decisions + explicit policies)
- Best example:
- Step 4 template:
templates/step4-completeness-consistency-template.md- Best example:
spec-windsurf-gpt5lr/step4-<timestamp>.md
- Best example:
- Step 5 template:
templates/step5-challenge-template.md- Best of:
spec-github-sonnet4/step5-<timestamp>.md(challenge breadth) andspec-windsurf-gpt5lr/step5-<timestamp>.md(decision capture)
- Best of:
- Step 6 template:
templates/step6-visuals-template.md- Best example:
spec-windsurf-gpt5lr/step6-<timestamp>.md
- Best example:
- Step 7 template: Follow GitHub Sonnet4 style for testability depth
- Best example:
spec-github-sonnet4/step7-<timestamp>.md
- Best example:
Process
- Step 1 — Clarify & Group (Pre-EARS) [AUTOMATED]
- Propose: Show domains to be extracted and a short gaps list based on the template.
- Act: Save
step1-<timestamp>.mdwith domain grouping and “Identified Gaps & Questions”.
- Step 2 — Transform to EARS [AUTOMATED]
- Propose: Outline domains and planned REQ blocks with Trigger/Condition/Response/Measure.
- Act: Save
step2-<timestamp>.mdwith strict EARS. Normalize flags (short-x, long--flag). Avoid policy claims pending Steps 3–5.
- Step 3 — Basic Quality Check [USER ENGAGEMENT REQUIRED]
- Propose: List contradictions, duplicates, scope/clarification items with numbered choices.
- Act: Save
step3-<timestamp>.mdand record decisions in a "Decisions and Clarifications" section. If terms/flags/policies change, add TODO: Refresh Step 2.
- Step 4 — Completeness & Consistency [USER ENGAGEMENT REQUIRED]
- Propose: Missing scenarios, edge cases, terminology consistency, alignment/determinism prompts.
- Act: Save
step4-<timestamp>.mdwith Decisions recorded and any conflict resolution policy. If terminology/flags change, add TODO: Refresh Step 2.
- Step 5 — Challenge, Simplify, Amplify [USER ENGAGEMENT REQUIRED]
- Propose: Web-researched challenge catalog: CLI UX, error taxonomy/exit codes, integrity/provenance, structured logging/redaction, retries/idempotency, multi-repo discovery safety, proxy/CA patterns, security hardening.
- Act: Save
step5-<timestamp>.mdwith Challenge/Simplification/Amplification and numbered decision prompts; include MoSCoW priorities; cite 1–2 reputable sources per area.
- Step 6 — Visual Documentation & Diagrams [AUTOMATED]
- IMPORTANT: Use a strong capable model for Mermaid (e.g., Sonnet 4). If a weaker model is used, mark output as baseline and schedule an upgrade.
- Propose: Diagram list and annotations drawn from Steps 1–5 decisions.
- Act: Save
step6-<timestamp>.mdwith:- High-level architecture
- Install flow (single-repo)
- Multi-repo interactive flow (plan + confirm)
- Retry/backoff state diagram
- Deterministic merge/conflict resolution
- Dry-run full plan
- Potential extras (if discovered via Copilot or analysis): error handling trees, artifact lineage, environment matrix visualization
- Step 2 Refresh (if needed)
- When Steps 3–5 alter flags/terms/policies, refresh Step 2 to keep EARS aligned. Overwrite the previous Step 2 with a new timestamped file and link decisions that motivated changes.
- Step 7 — Testability Assessment [AUTOMATED]
- Propose: Coverage grid and acceptance criteria categories; CI blocks; environment matrix.
- Act: Save
step7-<timestamp>.mdfollowing GitHub Sonnet4's structure:- Verification criteria framework (per requirement group)
- Installation process tests
- Git integration tests
- Performance benchmarks
- Error condition tests
- Security tests
- Acceptance test scenarios (end-to-end)
- Test automation framework and environment matrix
- Quality metrics and success thresholds
- Final Specification Consolidation [AUTOMATED]
- Critical for ESDI Phase 3: Create definitive specification file for design phase consumption
- Act: Save
specification.md(orspecification-final.md) with:- Complete EARS requirements from latest Step 2 (post-refresh if applicable)
- All decisions and clarifications from Steps 3-5 integrated
- Reference links to step files for traceability
- Clear structure for consumption by generate-design skill
- This file becomes the input for Phase 3 (generate-design) in ESDI workflow
- File name must be deterministic (no timestamp) for easy reference
Outputs to USER
- Present each generated step as Markdown.
- Summarize decisions and outstanding prompts.
- Confirm save locations under
[output_folder]. - Final deliverable:
specification.md- Consolidated EARS specification ready for Phase 3 (design)
Output Files Structure
[output_folder]/
├── step1-<timestamp>.md # Clarify & Group
├── step2-<timestamp>.md # Initial EARS
├── step2-<timestamp2>.md # Refreshed EARS (if applicable)
├── step3-<timestamp>.md # Quality Check + Decisions
├── step4-<timestamp>.md # Completeness + Decisions
├── step5-<timestamp>.md # Challenge + Decisions
├── step6-<timestamp>.md # Visual Documentation
├── step7-<timestamp>.md # Testability Assessment
└── specification.md # ⭐ FINAL consolidated EARS spec (for Phase 3)
Domain-Specific Notes
- Mermaid generation quality depends on the model; prefer strong models for Step 6.
- Use deterministic ordering and explicit conflict/precedence to maximize test determinism.
- Use the time helper or
scripts/now/binbinaries to ensure correct per-file timestamps.