format for flow documenation in LLM-assisted refactoring
This spec is given to the LLM which in turn utilizes it to
produce documentation of system flows, each showing
state transitions, steps, and side effects.
These flow documents support:
- verification on the LLM's understanding of current code structure
- splitting the refactoring process in more manageable phases.
- straightforward autogeneration of end-to-end tests
Produced formats
- gfm-markdown
- mermaid, if appropriate
The language is kept simple, clear & non-technical.
Compared to existing formats:
- More concrete than UML and DFDs - shows actual states not diagrams
- More dynamic than ADRs and RFCs - captures behavior not just decisions
- More machine-focused than BDD - optimized for LLM as well as human comprehension
You provide the entire spec with a directive follow this format...",
as part of a prompt.
Caution
make sure the LLM isn't missing any relevant files/source code
before you ask it to produce flows.
The following is a possible prompt:
User:
we're going to refactor the execution behavior of
a CLI tool that functions as a test-runner for unit tests.
This is the source code:
- foo/src/foo.js
- foo/src/bar.js
<replace-with-flow-directive>
System:
this looks like a system...
User:
Is there anything that looks unclear - or a referenced
file that I didn't provide?
System:
no, it looks simple and consice.
I have all the referenced files.
<produce-flows>
Replace the <produce-flows> placeholder with the entirety of
the following code block and send it back as a response.
I will now provide you with a specification text for a documentation format.
Your task is to:
1. READ the specification carefully - it explains how to document system flows
2. ANALYZE the source code I will provide
3. IDENTIFY all distinct flows (user-initiated and system-initiated)
4. DOCUMENT each flow following the format EXACTLY
The specification includes:
- Format definition
- Writing requirements
- Two example flows (for illustration only - do not include these)
Important notes:
- Each flow MUST follow the exact structure defined
- Each section MUST be complete (start state, steps, end state, etc.)
- Code elements MUST be enclosed in backticks
- Reference links MUST use [text][ref] format
- Line length SHOULD NOT exceed 70 characters
Before starting, you SHOULD:
1. Confirm you understand the format
2. Ask any clarifying questions
3. List the flows you've identified for validation
You MAY ask for clarification if any part is unclear.
Do you understand these requirements?
for clarifications so I can clear it up.
/* flow documentation format begins: */
## Structure
Flows are categorized into two types:
### User Flows
- Initiated by user actions
- Have clear UI interaction points
- Example: Login, registration, purchase
### System Flows
- Triggered by system events
- Example: Order processing, scheduled tasks
## Format
> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
> "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
> document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.html)
### Required Sections
Each flow **MUST** contain:
1. **Start State**
- Current page/view
- Complete user object
- System state
2. **Steps**
- UI interactions
- API endpoints
- Server operations
3. **End State**
- Resulting page/view
- Updated user object
- New system state
4. **Side Effects**
- External system changes
- Notifications/emails
- Analytics events
### Optional Elements
- Mermaid sequence diagrams
- Component diagrams
- State transition graphs
<!-- User flow example begins -->
## Examples
### 3.1.1
> Free to Paid Plan Switch
### start state
- `page`: `/pricing`
- `user`:
```yaml
id: user-123
payment_service_provider_customer_id: cus_xyz789
auth_token: eyJhbGciOiJIUzI1...
has_trialled: false
subscription:
id: sub_free123
plan:
id: price_free
nickname: Free
status: active
trial_end: null
cancel_at_period_end: false
latest_invoice: null
items: []
`\`\`\
### steps
1. `user` clicks "Subscribe" on paid plan card
- **UI**:
- `<plan-selector>` triggers selection
- `<subscription-modal>` opens
- **Endpoint**:
- `GET` `/api/v1/plans`
- **Server**:
- `PaymentService.getPlans()`
2. `user` enters payment details
- **UI**:
- `<payment-form>` validates input
- Shows loading state
- **Endpoint**:
- `POST` `/api/v1/payment_methods`
- **Server**:
- `PaymentService.validatePaymentMethod()`
- `PaymentService.attachToCustomer()`
3. `system` creates subscription
- **UI**:
- Shows processing state
- **Endpoint**:
- `POST` `/api/v1/subscription`
- **Server**:
- `UserService.createSubscription()`
- `PaymentService.createSubscription()`
4. `stripe` processes payment
- **UI**:
- Shows 3DS modal if required
- **Server**:
- Handles webhook
- Updates subscription status
### end state
- `page`: `/account`
- `user`:
```yaml
id: user-123
payment_service_provider_customer_id: cus_xyz789
auth_token: eyJhbGciOiJIUzI1...
has_trialled: false
subscription:
id: sub_xyz987
plan:
id: price_tutor
nickname: Tutor
amount: 2000
status: active
trial_end: null
cancel_at_period_end: false
latest_invoice:
payment_intent:
status: succeeded
items:
- price: price_tutor
quantity: 1
`\`\`\
### side effects
- `stripe` subscription created
- `stripe` payment method saved
- `system` sends welcome email
- `system` tracks `"subscription_created"` event
### components
#### ui
- `<plan-selector>`
- `<subscription-modal>`
- `<payment-form>`
- `<three-ds-modal>`
#### server
- `PaymentService`
- `UserService`
- `SubscriptionManager`
- `EmailService`
### omitted
Existing functionality not detailed in the main flow:
- Payment validation rules
- Subscription renewal logic
- Tax calculation
- Failed payment handling
<!-- User flow ends -->
<!-- System Flow Example begins -->
### 3.2.1
> Failed Payment Recovery
### start state
- `user`:
```yaml
id: user-123
payment_service_provider_customer_id: cus_xyz789
auth_token: eyJhbGciOiJIUzI1...
subscription:
id: sub_xyz987
plan:
id: price_tutor
nickname: Tutor
amount: 2000
status: past_due
trial_end: null
cancel_at_period_end: false
latest_invoice:
id: inv_123
payment_intent:
status: requires_payment_method
attempt_count: 1
next_payment_attempt: 1679529600
`\`\`\
### steps
1. `stripe` sends failed payment webhook
- **Endpoint**:
- `POST` `/webhooks/stripe`
- **Server**:
- `PaymentService.handleFailedPayment()`
- `UserService.updateSubscriptionStatus()`
- `NotificationService.scheduleReminders()`
2. `system` initiates recovery process
- **Server**:
- `PaymentService.getLastFailedInvoice()`
- `UserService.setGracePeriod()`
- `EmailService.sendPaymentFailedNotice()`
3. `system` attempts automatic retry
- **Server**:
- `PaymentService.retryPayment()`
- If 3DS required:
- `EmailService.sendPaymentAuthEmail()`
- Generate hosted invoice URL
4. `system` monitors recovery status
- **Server**:
- `PaymentService.checkPaymentStatus()`
- `UserService.refreshSubscription()`
- If still failed after grace period:
- `SubscriptionManager.deactivate()`
### end state
Success path:
```yaml
subscription:
status: active
latest_invoice:
payment_intent:
status: succeeded
`\`\`\
Failure path:
```yaml
subscription:
status: canceled
ended_at: 1679529600
cancel_at_period_end: false
`\`\`\
### side effects
- `system` sends payment failure email
- `system` updates subscription status
- `system` tracks `"payment_failed"` event
- `system` schedules reminder emails
- `system` sets grace period expiration
### components
#### server
- `PaymentService`
- `UserService`
- `SubscriptionManager`
- `NotificationService`
- `EmailService`
- `WebhookHandler`
### omitted
Existing functionality not detailed in the main flow:
- Dunning schedule configuration
- Payment provider error mapping
- Grace period calculations
- Customer support notification logic
<!-- System Flow Example ends -->