unravel

name	unravel
description	Build a deterministic end-to-end flow plan file for a user objective using the /unravel command. Use when the user asks for /unravel, asks to map full flow, or needs architecture plus sequence/state diagrams and a traceable execution narrative.

Unravel

/unravel Apply this skill when the user explicitly uses /unravel or requests an end-to-end flow breakdown with diagrams and a full execution narrative. theme (string) If the user provides /unravel <theme>, use the provided theme. If theme is omitted, infer it from the user request objective. Extract the shortest phrase that names the objective domain. Prefer noun-phrase scope over verbs. If multiple candidates remain, choose the first candidate in request order.

<theme_normalization> Trim leading and trailing spaces. Lowercase. Replace spaces and underscores with "-". Remove characters outside [a-z0-9-]. Collapse repeated "-". Remove leading and trailing "-". <empty_fallback>general-flow</empty_fallback> </theme_normalization>

<output_contract> <file_path_template>.cursor/plans/unravel-[theme].plan.md</file_path_template> <theme_source>[theme] must be the normalized theme from <theme_normalization>.</theme_source> <write_mode>Create or overwrite the file deterministically.</write_mode> </output_contract>

<hallucination_guardrails> <allowed_sources> User-provided context in the current request. Discovered repository context available at runtime. </allowed_sources> <forbidden_behavior>Do not invent systems, APIs, services, files, or constraints not evidenced by context.</forbidden_behavior> <missing_fact_rule>Mark every missing fact as "Assumption:" and keep assumptions minimal and testable.</missing_fact_rule> <critical_unknown_rule>If critical context is missing, include explicit unknowns and impact on confidence.</critical_unknown_rule> </hallucination_guardrails>

The plan explains the complete end-to-end flow of the user objective from input to final outcome. Include actors, ordered steps, decisions and branch logic, intermediate and final outputs, and failure paths with recovery behavior. Tie each major step directly to user intent.

<plan_structure> <optional_frontmatter_fields> name overview assumptions inputs outputs </optional_frontmatter_fields> <required_sections_order>

Objective

Scope and Assumptions

High-Level Flow

Detailed End-to-End Flow

Diagram 1 (Mermaid)

Diagram 2 (Mermaid)

Edge Cases and Failure Paths

Validation Checklist

Summary

</required_sections_order> <title_rule>After optional frontmatter, render an H1 title with the theme.</title_rule> </plan_structure>

<diagram_requirements> <minimum_count>2</minimum_count> <required_types> High-level architecture or flow diagram. Sequence diagram or state-flow diagram. </required_types> <consistency_rules> Nodes map to named actors or components in the narrative. Branch points align with described decisions. Outputs in diagrams match outputs in the detailed flow. </consistency_rules> </diagram_requirements>

<narrative_depth> <required_coverage> Trigger and input intake. Validation and gating. Orchestration steps. Branch conditions. Error and failure handling. Completion and final artifacts. </required_coverage> <branch_rule>Include key branches and failure paths, not only the happy path.</branch_rule> <language_rule>Use precise, technical, explicit language. Avoid vague statements.</language_rule> </narrative_depth>

<validation_checklist_requirements> Checklist with pass or fail style items. <required_items> Completeness of end-to-end flow. Consistency between narrative and both diagrams. Traceability of each major step to user objective. Explicit assumptions and unknowns. Inclusion of edge cases and failure paths. Correct output file naming rule usage. </required_items> </validation_checklist_requirements>

<execution_steps> Resolve and normalize theme. Resolve exact output path .cursor/plans/unravel-[theme].plan.md. Gather only allowed context under <hallucination_guardrails>. Generate the plan with <plan_structure> order and all required sections. Verify diagram count and type from <diagram_requirements>. Verify branch and failure coverage from <narrative_depth>. Verify checklist quality from <validation_checklist_requirements>. Save the file to the exact output path. </execution_steps>

/unravel payment-retry .cursor/plans/unravel-payment-retry.plan.md Context grounded in user and repository evidence. End-to-End Flow Explanation. Mermaid Diagram: System Flow. Mermaid Diagram: Sequence or State. Edge Cases and Failure Paths. Validation Checklist. Deterministic, structured, explicit, and technically precise. Reference constraints by XML tag names when enforcing behavior. Always use the normalized theme for output file naming. Write exactly one plan file to .cursor/plans/unravel-[theme].plan.md. Section order matches <plan_structure>. At least two Mermaid diagrams are present. Assumptions and unknowns are explicit and minimal.