docs(skill): adopt verbose plain-English voice for step data labels

[naorsabag]

Summary

The skill already locked in node label ≤ 4 words, but said nothing about the opposite voice for step data labels — which are the actual narration the user reads on hover and during the inspector walkthrough. Existing examples leaned on terse, code-flavored shorthand (POST /orders, INSERT item, query, response, charge \$card, auth ok) that reads as protocol annotation, not story. An agent pattern-matching off those examples will copy that style.

This PR encodes the rule and migrates every narrative example to match.

The rule

Node labels are billboards. Short, noun-phrase, identity-only, ≤ 4 words, no code names.
Step data labels are the narration. Verbose. Plain English. Explain WHAT is happening in the world, not the wire format. No code names, no HTTP verbs, no SQL, no method signatures.

SKILL.md changes

• New "Voice" section with an 8-row do/don't table covering common terse patterns and their plain-English rewrites.
• Inline "Quickest valid flow" rewritten so the first thing an agent copies already follows the rule.
• Explicit note that the rule applies to both the string form (data: \"…\") and the object's label: field. fields[] stays technical (it's a schema, not narration).

Examples migrated

• simple-crud.yaml — 4 steps
• auth-flow.yaml — 8 steps incl. parallel branch
• order-flow.yaml — 14 steps incl. parallel, create, destroy, sub-flow inner step
• self-loops.yaml — 8 steps incl. self-loops, multi-data, broadcast, parallel
• create-destroy.yaml — 4 steps (the new lifecycle demo)
• sub-flows.yaml — 6 outer + 2 inner steps

type-variants.yaml left as-is — it's a sprite/type showcase using data: \"→\" as connective tissue, not a narrative flow. Added an inline comment marking it as the deliberate exception so the agent doesn't pattern-match its terse style.

Test plan

• All 7 example YAMLs pass openhop validate (verified locally — ✓ Valid flow each).
• Prettier check clean (verified locally).
• Push each example and confirm the narration reads naturally in the inspector panel on hover.
• Agent test: ask "walk me through how an order is created" with this skill loaded and confirm the agent's output uses sentence-form narration, not POST /….

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Enhanced OpenHop skill documentation with improved guidance on authoring narrative-driven workflows and expanded examples for parallel flows.

• Chores

  • Updated example workflow files with more descriptive, narrative step descriptions for improved clarity.
  • Added new "Parallel Fan-out" example workflow demonstrating concurrent operations.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 99cdfbe1-120a-4631-9524-7fd600395b36

📥 Commits

Reviewing files that changed from the base of the PR and between 5338d30 and 4ccf456.

📒 Files selected for processing (9)

• examples/auth-flow.yaml
• examples/create-destroy.yaml
• examples/order-flow.yaml
• examples/parallel.yaml
• examples/self-loops.yaml
• examples/simple-crud.yaml
• examples/sub-flows.yaml
• examples/type-variants.yaml
• skills/openhop/SKILL.md

---

Walkthrough

This PR refactors OpenHop example YAML files to use descriptive narrative step descriptions instead of terse protocol terms, adds a new parallel checkout flow example, and updates skill documentation to define voice conventions for node labels (short identity phrases) versus step data (verbose world narration).

Changes

Example Narration Updates & Documentation

Layer / File(s)	Summary
Voice Guidelines & Documentation skills/openhop/SKILL.md	Adds "Voice" section defining node labels as short identity noun phrases (≤4 words, no code names) and step data as verbose plain-English world narration; updates template examples and parallel schema documentation.
Simple Narrative Updates examples/auth-flow.yaml, examples/create-destroy.yaml, examples/type-variants.yaml, examples/sub-flows.yaml	Step labels rewritten from terse protocol terms ("GET /login", "dequeued job", "→") to descriptive sentences explaining world events and handoffs between components.
Self-Loop Pattern Example examples/self-loops.yaml	Data payloads expanded with explicit labeled checks (schema validation, auth token, rate-limit bucket), metric emission, and cache confirmation; includes structured field definitions alongside narration.
CRUD Pattern Example examples/simple-crud.yaml	Step format expanded to include narrative text and structured data objects with label and fields (name/type with added markers) for create, insert, retrieve, and confirm operations.
Complex Order Flow Example examples/order-flow.yaml	Narrative descriptions added across 19 steps (validation, authorization, rate-limiting, payment, async events, retry); coupon_code field marked as removed; Stripe payment inputs restructured into separate charge amount/currency and order context descriptions.
New Parallel Fan-Out Example examples/parallel.yaml	New workflow definition modeling checkout with parallel inventory reservation and payment authorization branches; includes node metadata, field schemas with types, and narrative step descriptions.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• naorsabag/openhop#90: Updates to skills/openhop/SKILL.md guidance on node label length and truncation behavior.
• naorsabag/openhop#107: Imports and surfaces the updated YAML examples from this PR in web empty-state rendering.
• naorsabag/openhop#67: Prior updates to skills/openhop/SKILL.md documentation and workflow authoring guidance.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and clearly summarizes the main objective: adopting a verbose plain-English voice for step data labels in the skill documentation and examples.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/skill-verbose-step-prose

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}