Developer: Technical Documentation

Router command that creates technical documentation for stories or features.

Scope: In-code docs, API reference, architecture docs - documentation for developers.

Routing

Input	Strategy
story <path>	Story Technical Docs
feature <id>	Feature Technical Docs
<path> (auto-detect)	Detect from path pattern

---

Strategy: Story Technical Docs

Trigger: dev:document story <path> or auto-detected story path

Prerequisites

• Story status must be tested

Process

Phase 1: Analyze Implementation

1. Read implementation notes
2. Identify all files created/modified
3. Detect programming language(s)
4. Understand existing doc patterns

Phase 2: In-Code Documentation

For each file, add appropriate documentation:

JavaScript/TypeScript (JSDoc):

/**
 * Authenticates a user with credentials.
 *
 * @param email - User's email address
 * @param password - User's password
 * @returns Authentication result with token
 * @throws {AuthError} If credentials invalid
 *
 * @example
 * const result = await authenticate('user@example.com', 'pass');
 */

Python (Docstrings):

def authenticate(email: str, password: str) -> AuthResult:
    """
    Authenticate a user with credentials.

    Args:
        email: User's email address
        password: User's password

    Returns:
        AuthResult with token and user data

    Raises:
        AuthError: If credentials invalid

    Example:
        >>> result = authenticate('user@example.com', 'pass')
    """

Go (GoDoc):

// Authenticate verifies user credentials.
//
// Parameters:
//   - email: User's email address
//   - password: User's password
//
// Returns AuthResult and error if credentials invalid.
func Authenticate(email, password string) (*AuthResult, error) {

Phase 3: Technical Reference

Create {story_path}/dev-documentation.md:

# Technical Documentation: {Story Title}

## Overview

{Technical summary of implementation}

## Architecture

### Components

| Component | Purpose | Location |
|-----------|---------|----------|
| AuthService | Authentication logic | src/auth/service.ts |
| LoginForm | UI component | src/components/Login.tsx |

### Data Flow

User Input → LoginForm → AuthService → API → Session Store

## API Reference

### Functions

#### `authenticate(email, password)`

{Full documentation}

**Parameters**:
| Name | Type | Description |
|------|------|-------------|
| email | string | User email |
| password | string | User password |

**Returns**: `Promise<AuthResult>`

**Throws**: `AuthError`

**Example**:
```typescript
const result = await authenticate('user@example.com', 'pass');

Types

AuthResult

interface AuthResult {
  success: boolean;
  token?: string;
  user?: User;
  error?: string;
}

State Management

{How state is managed}

Error Handling

Error	Cause	Handling
AuthError	Invalid credentials	Show message
NetworkError	Connection failed	Retry logic

Testing

Unit Tests

Test	Location	Coverage
Auth flow	auth.test.ts	Login, logout

How to Run

npm test -- --grep "auth"

Dependencies

Package	Purpose
bcrypt	Password hashing
jsonwebtoken	Token generation

Notes

{Implementation decisions, gotchas}

#### Phase 4: Status Update

- Story status → `dev_documented`

### Output

✅ Story Technical Documentation Complete

Story: {title}

Documentation: ✅ In-code: 3 files documented ✅ Functions: 8 documented ✅ Reference: dev-documentation.md

→ Next (PO): po:validate story {story_path}

---

## Strategy: Feature Technical Docs

**Trigger**: `dev:document feature <id>` or auto-detected feature path

### Prerequisites

- Feature must be `feature_tested`
- All stories must be `dev_documented`

### Process

#### Phase 1: Gather Context

1. Read all story technical docs
2. Understand overall architecture
3. Identify cross-cutting concerns

#### Phase 2: Architecture Documentation

Create `.hefesto/features/{id}/docs/technical.md`:

```markdown
# Technical Documentation: {Feature Title}

## Architecture Overview

{High-level architecture description}

### System Diagram

┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Client │────▶│ Server │────▶│ Database │ └─────────────┘ └─────────────┘ └─────────────┘

### Components

| Component | Responsibility | Stories |
|-----------|---------------|---------|
| AuthModule | Authentication | 001, 002 |
| SessionManager | Session handling | 003 |

## File Structure

src/ ├── auth/ │ ├── service.ts # Core auth logic │ ├── session.ts # Session management │ └── types.ts # Type definitions ├── components/ │ └── Login.tsx # Login UI └── api/ └── auth.ts # API endpoints

## API Reference

### Endpoints

#### POST /api/auth/login

**Request**:
```json
{ "email": "string", "password": "string" }

Response:

{ "token": "string", "user": {...} }

Internal APIs

{Cross-story interfaces}

Data Models

User

interface User {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
}

State Management

{Feature-wide state handling}

Security Considerations

• {Security measure 1}
• {Security measure 2}

Performance Considerations

• {Optimization 1}
• {Optimization 2}

Testing Strategy

Unit Tests

{Coverage summary}

Integration Tests

{What's tested}

Deployment

{Deployment notes}

Monitoring

{What to monitor}

Story Documentation

Story	Technical Docs
001	Link
002	Link

#### Phase 3: Status Update

Update feature (does not change workflow flags - feature testing already sets those)

### Output

✅ Feature Technical Documentation Complete

Feature: {title}

Documentation: 📄 Architecture: docs/technical.md 📚 Story docs: 5 files linked

→ Next (PO): po:validate feature {id}

---

## Documentation Principles

1. **Document for developers**: Assume technical knowledge
2. **Explain the "why"**: Not just what, but why designed this way
3. **Include examples**: Working code samples
4. **Keep it current**: Update with code changes
5. **Link, don't duplicate**: Reference story docs