---

name: epic-documentation-standards description: Artifact formatting standards and diagram guidelines for epic workflow documentation. Use when creating research artifacts, implementation plans, or validation reports. Triggers when you need to "format documentation", "add diagrams", "improve artifact formatting", "use mermaid diagrams", "visualize architecture", or "create visual documentation". allowed-tools:

• Read
• Write

---

Documentation Standards

Formatting and visualization standards for epic workflow artifacts. This skill defines when and how to use diagrams, tables, and other visual elements in research, planning, and validation documents.

Mermaid Diagram Types

Flowcharts

Use for:

• Data flow through system components
• Decision trees and conditional logic paths
• Process workflows with branching
• Algorithm steps

Example - Data Flow:

flowchart TD
    A[User Request] --> B{Auth Check}
    B -->|Valid| C[Load User Data]
    B -->|Invalid| D[Return 401]
    C --> E[Transform Response]
    E --> F[Send to Client]

Syntax:

```mermaid
flowchart TD
    A[Node] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[Alternative]

**Node shapes:**
- `[Rectangle]` - Process/action
- `{Diamond}` - Decision point
- `([Rounded])` - Start/end
- `[(Database)]` - Data store

### Sequence Diagrams

**Use for:**
- API interactions between services
- Request/response flows
- Component communication patterns
- Authentication flows
- Multi-step transactions

**Example - API Interaction:**
```mermaid
sequenceDiagram
    participant Client
    participant API
    participant DB
    participant Cache

    Client->>API: POST /users
    API->>DB: Check if user exists
    DB-->>API: Not found
    API->>DB: Create user record
    DB-->>API: User created
    API->>Cache: Invalidate user cache
    Cache-->>API: OK
    API-->>Client: 201 Created

Syntax:

```mermaid
sequenceDiagram
    participant A
    participant B
    A->>B: Synchronous call
    B-->>A: Response
    A->>+B: Activate
    B->>-A: Deactivate

**Arrow types:**
- `->>` Solid line (synchronous)
- `-->>` Dotted line (response)
- `->>+` Activate participant
- `->>-` Deactivate participant

### Class Diagrams

**Use for:**
- Component architecture and relationships
- Data model structures
- Interface definitions
- Inheritance hierarchies

**Example - Component Relationships:**
```mermaid
classDiagram
    class AuthService {
        +login(credentials)
        +logout(token)
        +validateToken(token)
        -hashPassword(password)
    }

    class UserRepository {
        +findById(id)
        +create(userData)
        +update(id, data)
    }

    class TokenManager {
        +generate(userId)
        +verify(token)
        +revoke(token)
    }

    AuthService --> UserRepository
    AuthService --> TokenManager

Syntax:

```mermaid
classDiagram
    class ClassName {
        +publicMethod()
        -privateMethod()
        +field: Type
    }
    ClassA --> ClassB : uses
    ClassC --|> ClassD : inherits

**Relationship types:**
- `-->` Association
- `--|>` Inheritance
- `--*` Composition
- `--o` Aggregation

### State Diagrams

**Use for:**
- State machines and transitions
- Component lifecycle
- Workflow status tracking
- Feature flags or toggles

**Example - Order Lifecycle:**
```mermaid
stateDiagram-v2
    [*] --> Pending
    Pending --> Processing: Payment Confirmed
    Processing --> Shipped: Items Packed
    Processing --> Cancelled: User Cancelled
    Shipped --> Delivered: Arrival Confirmed
    Delivered --> [*]
    Cancelled --> [*]

Syntax:

```mermaid
stateDiagram-v2
    [*] --> State1
    State1 --> State2: Event
    State2 --> [*]

## Artifact Formatting Standards

### Research Artifacts (codebase-research.md, docs-research.md)

**Structure:**
```markdown
# [Topic] Research

## Overview
[Brief summary - 2-3 sentences]

## Key Findings
1. **Finding**: Description with file:line references
2. **Finding**: Description with documentation URLs

## Component Analysis

### Component Name
**Location**: `path/to/file.ts:45-120`

**Purpose**: [What it does]

**Key Methods/Functions:**
- `methodName()` (line 67): [what it does]
- `otherMethod()` (line 89): [what it does]

**Dependencies:**
- Imports: `import { X } from 'y'` (line 3)
- External: library@version

[Mermaid diagram if complex]

## Patterns Observed
- Pattern 1: Description + examples
- Pattern 2: Description + examples

Rules:

• Every claim must cite file:line or URL
• Use tables for comparing multiple similar items
• Use diagrams for 3+ interconnected components
• Keep overview sections factual (no opinions)

Implementation Plans (plan.md)

Structure per phase:

## Phase N: [Descriptive Name]

### Changes
| File | Action | Description |
|------|--------|-------------|
| `path/to/file.ts:45-67` | Modify | [specific change] |
| `path/to/new.ts` | Create | [what it contains] |

### Implementation Details
[Step-by-step specifics, referencing research]

[Mermaid diagram if architecture changes]

### Verification
**Automated:**
- [ ] `npm test` - [what it verifies]
- [ ] `npm run lint` - passes

**Manual:**
- [ ] [Human check with specific criteria]

Rules:

• File paths must include line ranges when modifying
• Actions: Create, Modify, Delete only
• Every phase needs verification section
• Use sequence diagrams for multi-step changes
• Use flowcharts for conditional logic additions

Validation Reports (validation.md, review.md)

Structure:

# [Phase/Feature] Validation

## Status: [PASS | FAIL | PARTIAL]

## Test Results
| Suite | Tests | Passed | Failed | Duration |
|-------|-------|--------|--------|----------|
| Unit | 42 | 42 | 0 | 2.3s |
| Integration | 12 | 11 | 1 | 5.1s |

## Failed Tests
### test-suite-name
**File**: `path/to/test.ts:34`
**Error**:

[error message - trimmed to essential]

**Impact**: [critical | moderate | minor]

## Static Analysis
- Lint: ✓ PASS
- Type Check: ✓ PASS
- Build: ⚠ WARNING ([brief description])

Rules:

• Use tables for test summaries
• Only show failed test details (pass counts are enough)
• Trim stack traces to relevant lines
• Use status symbols: ✓ ⚠ ✗

Visual Hierarchy Guidelines

Headers

• # Document title only
• ## Major sections
• ### Subsections
• #### Rarely needed (consider restructuring if you need this)

Emphasis

• Bold for labels, findings, emphasis
• Code for file paths, code references, commands
• Italic sparingly (prefer bold or structure)

Lists vs Tables vs Diagrams

Use unordered lists when:

• Items are independent
• Order doesn't matter
• 2-7 simple items

Use ordered lists when:

• Sequence matters (steps, phases)
• Items reference each other by number

Use tables when:

• Comparing multiple items across dimensions
• Structured data (test results, file changes)
• 3+ columns of related information

Use diagrams when:

• 3+ interconnected components
• Flow has branches or loops
• Relationships are non-linear
• Architecture or interaction patterns

Code Block Conventions

File References

// path/to/file.ts:45-52
export function authenticate(token: string): User {
  const decoded = verifyToken(token);
  return getUserById(decoded.userId);
}

Diff-style Changes

- const user = await db.findUser(id);
+ const user = await userRepository.findById(id);

Command Output

$ npm test
✓ auth.test.ts (4 tests passed)
✗ user.test.ts (1 test failed)

Formatting Checklist

Before finalizing any artifact:

• Headers follow hierarchy (no skipping levels)
• All file references include paths (with line numbers if modifying)
• All external references include URLs
• Tables used for structured comparisons
• Diagrams included for complex flows (3+ components)
• Code blocks have language specified
• Lists are parallel in structure
• Status indicators consistent (✓ ⚠ ✗)

Common Mistakes to Avoid

1. Vague file references - Always include full paths

   • Bad: "in the auth file"
   • Good: "src/auth/service.ts:67"

2. Orphaned diagrams - Context before and after

   • Bad: [diagram with no explanation]
   • Good: "The authentication flow involves three services:" [diagram] "This pattern ensures..."

3. Walls of text - Break up with structure

   • Use headers, lists, tables to create visual breathing room

4. Inconsistent terminology - Pick terms and stick to them

   • Don't alternate between "user model" and "user entity"

5. Missing diagram labels - All nodes should be clear

   • Bad: A --> B --> C
   • Good: Client --> API --> Database

References

• Mermaid docs: https://mermaid.js.org/
• Markdown guide: https://www.markdownguide.org/