name	documentation
description	Maintain documentation for IntelliFill following Diátaxis framework. Use when creating or updating docs, API references, or guides.

Documentation Maintenance Skill

Name: documentation
Author: Intellifill

This skill provides comprehensive guidance for maintaining IntelliFill documentation following the Diátaxis framework.

Documentation Architecture
Diátaxis Framework
Frontmatter Standards
Writing Guidelines
Update Triggers
Code Examples
Cross-Referencing
ADR Pattern

Documentation Architecture

IntelliFill uses a structured, multi-location documentation system.

Documentation Locations

IntelliFill/
├── docs/                          # Root-level Diátaxis docs
│   ├── README.md                  # Documentation hub
│   ├── MAINTENANCE.md             # This guide
│   ├── tutorials/                 # Learning-oriented
│   ├── how-to/                    # Problem-oriented
│   ├── reference/                 # Information-oriented
│   │   ├── api/
│   │   │   ├── endpoints.md
│   │   │   └── schemas.md
│   │   ├── configuration/
│   │   │   └── environment.md
│   │   └── database/
│   │       └── schema.md
│   └── explanation/               # Understanding-oriented
│       └── architecture.md
├── quikadmin/
│   ├── docs/                      # Backend-specific docs
│   └── CLAUDE.md                  # Backend AI context
├── quikadmin-web/
│   ├── docs/                      # Frontend-specific docs
│   └── CLAUDE.md                  # Frontend AI context
├── CLAUDE.local.md                # Local dev context
└── AGENTS.md                      # Task Master integration

Documentation Hierarchy

1. CLAUDE.local.md        → Local dev overrides (not in git)
2. [subproject]/CLAUDE.md → Subproject-specific context
3. docs/                  → Unified Diátaxis documentation
4. README.md              → Project overview
5. AGENTS.md              → Agent integration guide

Diátaxis Framework

IntelliFill documentation follows the Diátaxis framework with four quadrants.

Four Quadrants

                Learning          Practical
              ┌─────────────┬─────────────┐
              │             │             │
    Practical │  Tutorials  │  How-To     │
              │             │             │
              ├─────────────┼─────────────┤
              │             │             │
 Theoretical  │ Explanation │  Reference  │
              │             │             │
              └─────────────┴─────────────┘

1. Tutorials (Learning-Oriented)

Purpose: Help newcomers learn by doing

Characteristics:

Step-by-step instructions
Beginner-friendly
Repeatable and reliable
Complete examples
Focus on learning, not production

Example Structure:

---
title: Building Your First PDF Form
description: Learn IntelliFill basics by creating and filling a simple form
category: tutorials
difficulty: beginner
duration: 30 minutes
---

# Building Your First PDF Form

In this tutorial, you'll learn the basics of IntelliFill by creating a simple
PDF form and automatically filling it with data.

## What You'll Learn

- Uploading documents
- Creating templates
- Mapping form fields
- Generating filled PDFs

## Prerequisites

- IntelliFill account
- Sample PDF form (provided)
- 30 minutes

## Step 1: Upload Your First Document

First, let's upload a sample invoice...

[Detailed step-by-step instructions]

## What You've Learned

Congratulations! You've successfully...

## Next Steps

- [Tutorial: Advanced Field Mapping](./advanced-mapping.md)
- [How-To: Batch Process Documents](../how-to/batch-processing.md)

2. How-To Guides (Problem-Oriented)

Purpose: Solve specific problems

Characteristics:

Goal-oriented
Assume knowledge
Show one way to do something
Practical and actionable
Production-focused

Example Structure:

---
title: How to Implement Rate Limiting
description: Add rate limiting to API endpoints
category: how-to
tags: [api, security, backend]
---

# How to Implement Rate Limiting

This guide shows you how to add rate limiting to protect your API endpoints.

## Problem

You need to prevent API abuse by limiting request rates per user.

## Solution

Use the built-in rate limiter middleware.

## Prerequisites

- Backend development environment
- Basic Express.js knowledge

## Steps

### 1. Import the Rate Limiter

```typescript
import { rateLimiter } from '@/middleware/rateLimiter';

2. Apply to Routes

[Detailed implementation steps]

Verification

Test your rate limiting...

Troubleshooting

If rate limiting isn't working...

Frontmatter Standards

All documentation files must include frontmatter.

Frontmatter Template

---
title: Short, Descriptive Title
description: One-line summary of the document
category: tutorials | how-to | reference | explanation
tags: [tag1, tag2, tag3]
difficulty: beginner | intermediate | advanced  # (tutorials only)
duration: 15 minutes | 1 hour                  # (tutorials only)
lastUpdated: 2024-01-15                        # (optional)
---

Frontmatter Examples

Tutorial:

---
title: Getting Started with IntelliFill
description: Learn the basics in 30 minutes
category: tutorials
difficulty: beginner
duration: 30 minutes
tags: [getting-started, basics]
---

How-To:

---
title: How to Add Custom Validation
description: Implement custom validation for form fields
category: how-to
tags: [validation, backend, forms]
---

Reference:

---
title: Environment Variables Reference
description: Complete list of environment variables
category: reference
tags: [configuration, environment]
---

Explanation:

---
title: Document Processing Pipeline
description: Understanding how documents flow through the system
category: explanation
tags: [architecture, processing, ocr]
---

Writing Guidelines

Voice and Tone

Active voice: "Click the button" not "The button should be clicked"
Present tense: "The system validates" not "The system will validate"
Direct address: "You can configure" not "One can configure"
Concise: Remove unnecessary words
Clear: Use simple language

Formatting Standards

Headings:

# H1: Document Title (only one per page)
## H2: Major Sections
### H3: Subsections
#### H4: Minor Subsections (avoid if possible)

Lists:

- Unordered lists for items without sequence
1. Ordered lists for steps or sequences
- Use sentence case
- End with periods if complete sentences
- No periods for fragments

Code:

`inline code` for variables, commands, filenames

```language
code blocks for examples

Supported languages: typescript, javascript, bash, json, yaml, prisma, sql


**Emphasis**:
```markdown
**Bold** for UI elements, important terms
*Italic* for emphasis (use sparingly)
`code` for technical terms

File Naming

Use kebab-case: api-endpoints.md, getting-started.md
Be descriptive: authentication-flow.md not auth.md
Avoid dates in names unless part of ADR

Update Triggers

Documentation MUST be updated when:

API Changes

Trigger: Adding, modifying, or removing API endpoints

Update:

docs/reference/api/endpoints.md
Relevant how-to guides
CLAUDE.local.md if affects local dev

Example:

# docs/reference/api/endpoints.md

### Upload Document

```http
POST /api/documents/upload

Added: v1.2.0 (2024-01-15) Updated: v1.3.0 (2024-02-01) - Added multipart support

[Documentation...]


### Environment Variables

**Trigger**: Adding or changing environment variables

**Update**:
- `docs/reference/configuration/environment.md`
- `.env.example`
- CLAUDE.local.md (Environment Variables section)

### Database Schema

**Trigger**: Prisma migrations

**Update**:
- `docs/reference/database/schema.md`
- CLAUDE.local.md if affects common queries

### Known Issues

**Trigger**: Fixing or discovering bugs

**Update**:
- CLAUDE.local.md (Known Issues section)
- Mark as ✅ FIXED when resolved

### New Features

**Trigger**: Implementing new features

**Update**:
- Tutorial (if beginner-focused)
- How-to guide (if problem-solving)
- Reference docs (for API/config)
- Explanation (for architecture)

## Code Examples

### Code Example Standards

**Always include**:
1. Language identifier in code fence
2. Complete, runnable examples
3. Comments for clarity
4. Error handling
5. Type annotations (TypeScript)

**Good Example**:
```typescript
// quikadmin/src/services/document.service.ts
import { PrismaClient } from '@prisma/client';
import { AppError } from '@/utils/errors';

export class DocumentService {
  private prisma: PrismaClient;

  constructor(deps: { prisma: PrismaClient }) {
    this.prisma = deps.prisma;
  }

  /**
   * Retrieve a document by ID with ownership check
   */
  async getById(id: string, userId: string) {
    const document = await this.prisma.document.findFirst({
      where: { id, userId },
    });

    if (!document) {
      throw new AppError('Document not found', 404);
    }

    return document;
  }
}

Bad Example:

// Don't do this - incomplete, no context, no types
async getById(id, userId) {
  return prisma.document.findFirst({ where: { id, userId } });
}

Code Block Headers

Include file paths for context:

// quikadmin/src/api/documents.routes.ts
import { Router } from 'express';

const router = Router();
// ...

Placeholder Values

Use descriptive placeholders:

# Good
curl -X POST http://localhost:3002/api/documents \
  -H "Authorization: Bearer YOUR_AUTH_TOKEN" \
  -d '{"name": "Invoice.pdf"}'

# Bad
curl -X POST http://localhost:3002/api/documents \
  -H "Authorization: Bearer xxx" \
  -d '{"name": "abc"}'

Cross-Referencing

Internal Links

- [Tutorial: Getting Started](../tutorials/getting-started.md)
- [Reference: API Endpoints](./api/endpoints.md)
- [How-To: Rate Limiting](../how-to/rate-limiting.md)

Link Text Standards

# Good
See [How to Add Validation](../how-to/validation.md) for details.

# Bad
See [here](../how-to/validation.md) for details.
Click [this link](../how-to/validation.md).

ADR Pattern

Architecture Decision Records document significant decisions.

ADR Location

docs/decisions/
├── 0001-use-supabase-auth.md
├── 0002-monorepo-with-docker.md
├── 0003-tailwindcss-4-migration.md
└── template.md

ADR Template

---
title: ADR-0001: Use Supabase for Authentication
description: Decision to use Supabase Auth over custom JWT
category: explanation
tags: [adr, architecture, auth]
status: accepted | rejected | superseded | deprecated
date: 2024-01-15
---

# ADR-0001: Use Supabase for Authentication

## Status

Accepted (2024-01-15)

## Context

We need a secure, scalable authentication system for IntelliFill. Key requirements:

- Email/password authentication
- OAuth providers (Google, GitHub)
- Email verification
- Password reset
- Session management
- Minimal maintenance overhead

## Decision

We will use Supabase Auth for user authentication.

## Consequences

### Positive

- Industry-standard security practices
- Built-in features (verification, reset, OAuth)
- Scales automatically
- Well-documented
- Active community

### Negative

- External dependency
- Vendor lock-in risk
- Requires Supabase account
- Additional cost at scale

### Neutral

- Team needs to learn Supabase Auth
- Migration path exists if needed

## Alternatives Considered

### 1. Custom JWT Implementation

**Pros**: Full control, no dependencies
**Cons**: Security burden, ongoing maintenance

### 2. Auth0

**Pros**: Feature-rich, enterprise-ready
**Cons**: Expensive, complex setup

### 3. Passport.js

**Pros**: Flexible, many strategies
**Cons**: DIY security, more setup

## References

- [Supabase Auth Documentation](https://supabase.com/docs/guides/auth)
- [OAuth2 Specification](https://oauth.net/2/)

Best Practices

Update documentation WITH code changes - Not after
Use examples from actual code - Keep them in sync
Test all code examples - Ensure they work
Link related documents - Help readers navigate
Use consistent terminology - Don't vary terms
Keep it current - Remove outdated information
Use version markers - Note when things changed
Include prerequisites - Don't assume knowledge
Provide context - Explain why, not just how
Review regularly - Audit docs quarterly

Maintenance Checklist

When making changes:

Updated relevant Diátaxis documents
Updated CLAUDE.local.md if affects local dev
Updated .env.example if new env vars
Added/updated code examples
Tested all code examples
Cross-referenced related docs
Updated lastUpdated date
Reviewed for clarity and completeness

documentation

Install Skill

SKILL.md