SpillwaveSolutions/document-specialist-skill / skills/documentation-specialist
documentation-specialist
VerifiedThis skill should be used when creating professional software documentation (SRS, PRD, OpenAPI, SDD, architecture docs, user manuals, tutorials, runbooks) from templates (greenfield) or reverse-engineering documentation from existing code like Spring Boot or FastAPI (brownfield). Also handles documentation audits/reviews, format conversion (Markdown, DOCX, PDF), and diagram generation (Mermaid first: C4, sequence, class, ER, state, flowchart; PlantUML Salt for UI wireframes and leftover UML). Use when asked to "create documentation", "document my code", "write SRS", "generate PRD", "write DESIGN_DOC.md", "architecture document", "wireframe", or "documentation specialist".
references/reference/04-diagrams-state-vs-activity.md
View on GitHub# Diagrams: State Machine vs. Activity Diagram
---
TOKEN_BUDGET: 350
TIER: 3
LOAD_TRIGGER: On-demand when choosing between state machine and activity diagrams
DEPENDENCIES: 04-diagrams-selection.md
---
## 4.2 State Machine vs. Activity Diagram
### State Machine Diagram
**Purpose**: Model the **states** of a single object and **event-driven transitions**
**Focus**: Object behavior based on its current state
**Key Elements**: States (circles), Events (triggers), Transitions (arrows)
**Use When**: System behavior changes based on state (e.g., Order: Pending → Processing → Shipped)
**Example: Task Lifecycle**
```plantuml
@startuml
[*] --> Pending
Pending --> InProgress : assign_user
InProgress --> InReview : submit_for_review
InReview --> Completed : approve
InReview --> InProgress : reject
Completed --> [*]
@enduml
```
**Characteristics:**
- Event-driven (waits for events to trigger transitions)
- Models a single object's lifecycle
- Shows what states are valid and invalid transitions
---
### Activity Diagram
**Purpose**: Model **workflows, processes, or algorithms**
**Focus**: Flow of activities with decisions and parallelism
**Key Elements**: Activities (rectangles), Decisions (diamonds), Forks/Joins (bars)
**Use When**: Showing business processes with parallel steps (e.g., user registration flow)
**Example: Task Creation Workflow**
```plantuml
@startuml
start
:User clicks "New Task";
:Enter task details;
:Validate input;
if (Valid?) then (yes)
:Save to database;
fork
:Send email notification;
fork again
:Update analytics;
end fork
:Display success message;
else (no)
:Display error message;
endif
stop
@enduml
```
**Characteristics:**
- Action-driven (flows automatically from step to step)
- Models processes or algorithms
- Shows parallel execution with forks/joins
---
### Key Difference
**State diagrams wait for events; activity diagrams flow automatically.**
### Decision Guide
| Question | State Machine | Activity Diagram |
|----------|---------------|------------------|
| Am I modeling an object's lifecycle? | ✅ Yes | ❌ No |
| Does behavior depend on current state? | ✅ Yes | ❌ No |
| Am I showing a workflow with steps? | ❌ No | ✅ Yes |
| Do steps execute in parallel? | ❌ No | ✅ Yes |
| Is it event-driven? | ✅ Yes | ❌ No |
---
**End of State Machine vs. Activity Diagram Guide**
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |