block-journey

Files (1)

• SKILL.md

SKILL.md (first lines)

# Skill: block-journey

## When to Use

Run `/block-journey <name>` to document how a block or component works from two perspectives: the editor creating content, and the visitor consuming it. Use when onboarding to an unfamiliar block, before modifying one, or after building one to capture its contracts.

Parse `$ARGUMENTS` to extract the block name and an optional path scope:

- **`accordion`** — search the entire working directory for a block named "accordion"
- **`rte-blocks/accordion`** — search only within directories whose path contains "rte-blocks" for "accordion"
- **`mu-plugins/rtm-blocks/faq`** — search only within directories whose path contains "mu-plugins/rtm-blocks" for "faq"

If `$ARGUMENTS` contains a `/`, treat everything before the last `/` as a **path substring filter** and everything after as the block name. Match the filter against the full directory path, not just the immediate parent. This matters when the same plugin name exists under different parent directories (e.g., `plugins/rtm-blocks` vs `mu-plugins/rtm-blocks`). If no `/`, treat the entire argument as the block name and search broadly.

When the path filter matches multiple locations, list them and ask the user which one to document.

If `$ARGUMENTS` is empty, ask the user which block or component to document.

Do NOT modify any source files. This is documentation, not implementation.

## Method

### Step 1: Discover Files

Search the working directory for all files related to the block name from `$ARGUMENTS`. Do not assume a specific file structure — discover what exists.

Look for:
- **Registration files** — block metadata, config, or schema (JSON, YAML, PHP, JS)
- **Editor files** — edit components, sidebar controls, inspector panels, editor styles
- **Save / render files** — save components (static blocks), PHP render callbacks, server-side templates
- **Front-end behaviour** — JS that runs on page load for interactivity (toggles, carousels, modals, tabs)
- **Styles** — CSS/SCSS for both editor and front-end
- **Shared components** — any reusable pieces the block imports or depends on
- **Template partials** — theme-side templates that render the block's output

Use Grep and Glob to find files by name pattern and by references (imports, function calls, class names). Follow the dependency chain — if a file imports another, include it.

Present what was found:

```
## Discovered Files

| File | Role |
|---|---|
| path/to/block.json | Registration / attribute schema |
| path/to/edit.js | Editor component |
| path/to/frontend.js | Front-end toggle behaviour |
| ... | ... |
```

If no files are found, tell the user and stop.

### Step 2: Read and Map

Read each discovered file. Build a mental model of:

1. **Data model** — What attributes does the block store? What shape is the data?
2. **Editor interactions** — What can the editor do? What's inline vs sidebar? What inner blocks are allowed?
3. **Render pipeline** — How does saved data become HTML? Is it a static save (JS) or dynamic render (PHP)?
4. **Front-end behaviour** — What JS runs on page load? What DOM elements does it query? What state does it manage?
5. **DOM contract** — What classes, IDs, data attributes, and ARIA attributes connect the rendered HTML to front-end JS?

### Step 3: Write the Journey Document

Write to the **current project's** `docs/journeys/` directory (relative to the working directory). Create the directory if it doesn't exist.

Write to `docs/journeys/<block-name>.md` using the template below. Adapt sections to what actually exists — skip sections that don't apply (e.g., no "Front-End Journey" if the block has no interactive JS).

---

## Output Template

```
# <Block Name> — User Journeys

**Generated:** <YYYY-MM-DD>
**Source:** <plugin or directory where the block lives>

## Files

| File | Role |
|---|---|
| ... | ... |

## Data Model

List of attributes the block stores, their types, defaults, and purpose.

| Attribute | Type | Default | Purpose |
|---|---|---|---|
| ... | ... | ... | ... |

## Editorial Journey

Step-by-step description of what an editor does when using this block in the block editor. Cover:

1. How the block is inserted
2. What content is editable inline on the canvas (RichText, MediaUpload, etc.)
3. What controls live in the sidebar (InspectorControls)
4. How inner blocks work (if any) — what's allowed, how to add/remove
5. What the editor sees vs what the visitor sees (e.g., all items expanded in editor, collapsed on front-end)

Number each step. Be specific about which component or attribute is involved.

## Render Pipeline

How saved data becomes HTML. Describe the path:

- **Static save:** JS save component outputs markup directly
- **Dynamic render:** PHP callback receives attributes → sanitises → passes to template → template outputs HTML

Include the key markup structure (simplified) showing the wrapper, key child elements, and their classes/attributes.

## Front-End Journey

Step-by-step description of what a visitor experiences. Cover:

1. Initial page load state (what's visible, what's hidden)
2. Each interaction and what it triggers (click, hover, scroll, etc.)

From stuartshields/claude-setup, MIT.

More from stuartshields/claude-setup