OGT Docs - Documentation as Source of Truth

Philosophy

Documentation is the database of decisions. Code is merely its implementation.

┌─────────────────────────────────────────────────────────────────┐
│                    THE DOC-FIRST PRINCIPLE                      │
├─────────────────────────────────────────────────────────────────┤
│  1. Documentation DEFINES what something IS                     │
│  2. Code IMPLEMENTS what documentation specifies                │
│  3. Conflicts RESOLVE in favor of documentation                 │
│                                                                 │
│  If docs say X and code does Y → CODE IS WRONG                  │
└─────────────────────────────────────────────────────────────────┘

When to Use This Skill

Use ogt-docs when you need to:

• Understand the docs/ folder structure
• Find the right sub-skill for a specific task
• Initialize a new docs-first project
• Navigate between definition types

For specific tasks, use the specialized sub-skills listed below.

Documentation Structure Overview

docs/
├── definitions/              # WHAT things ARE
│   ├── business/             # Business model, pricing, users
│   ├── features/             # Product features and specs
│   ├── technical/            # Architecture, services, data
│   └── domain/               # Domain-specific concepts
│
├── rules/                    # HOW to IMPLEMENT
│   ├── code/                 # Coding standards
│   │   ├── frontend/
│   │   ├── backend/
│   │   └── infra/
│   ├── git/                  # Version control rules
│   └── domain/               # Domain-specific rules
│
├── todo/                     # TASK management
│   ├── pending/              # Not started
│   ├── in_progress/          # Being worked on
│   ├── review/               # Awaiting review
│   ├── blocked/              # Cannot proceed
│   ├── done/                 # Completed & verified
│   └── rejected/             # Declined tasks
│
├── guides/                   # HOW-TO documents
│   └── {topic}/
│
└── social/                   # Marketing & communications
    ├── campaigns/
    ├── content/
    └── branding/

The Folder-as-Entity Pattern

Every documentable item is a folder containing:

{item_slug}/
├── {type}.md                 # Primary document (task.md, feature.md, etc.)
├── {supporting_files}.md     # Additional documentation
└── .{signal_files}           # Status markers and metadata

Benefits:

• Move entire folder between workflow stages
• Attach unlimited supporting files
• Signal status via dot-files
• Version and track changes atomically

Sub-Skills Reference

Definitions (WHAT things ARE)

Rules (HOW to IMPLEMENT)

Tasks (WHAT to DO)

Other

Workflow Overview

flowchart TB
    subgraph define ["1. DEFINE"]
        D1[Create Definition]
        D2[Get Approval]
    end

    subgraph regulate ["2. REGULATE"]
        R1[Create Rules]
        R2[Add Examples]
    end

    subgraph implement ["3. IMPLEMENT"]
        I1[Create Task]
        I2[Write Code]
        I3[Review]
    end

    subgraph verify ["4. VERIFY"]
        V1[Run Checks]
        V2[Confirm Match]
    end

    define --> regulate --> implement --> verify
    verify -->|Mismatch| implement
    verify -->|Docs Wrong| define

Quick Start

"I need to define something new"

→ Use ogt-docs-define to understand types, then the specific sub-skill

"I need to create a task"

→ Use ogt-docs-create-task

"I need to check if a task is really done"

→ Use ogt-docs-audit-task

"I need to add coding rules"

→ Use ogt-docs-rules-code or the specific frontend/backend/infra variant

"I need to set up docs for a new project"

→ Use ogt-docs-init

Naming Conventions

Signal Files Reference

Signal files are dot-files that indicate status or metadata.

The Golden Rules

1. If it's not documented, it doesn't exist
2. If code contradicts docs, code is wrong
3. Never trust "done" status without verification
4. Move folders, don't copy files
5. Signal with dot-files, don't edit status fields