docs/README.md

Docs

This directory is the system-of-record for durable project knowledge.

Quick Links

Category	Index	Type	Purpose
Guides	guides/README.md	how-to	Practical step-by-step procedures
Design	design-docs/index.md	explanation	Feature design, ADRs, decision rationale
ADR Template	design-docs/decisions/0001-template.md	reference	Decision record template
Core Beliefs	design-docs/core-beliefs.md	explanation	Agent-first operating principles
Discovery	discovery/index.md	explanation	Validate ideas and capture taste
Delivery Specs	delivery-specs/index.md	reference	Engineering handoff specs
Exec Plans	exec-plans/README.md	how-to	Complex multi-step work tracking
Tech Debt	exec-plans/tech-debt-tracker.md	how-to	Known debt and cleanup opportunities
Exploration	exploration/README.md	exploration	Ideas, research, scratchpad
Learnings	learnings/README.md	reference	Durable patterns from completed work
Archived Learnings	learnings/archived/README.md	reference	Overflow learnings archive
References	references/README.md	reference	External docs for agent context

Learnings by Category

Category	File
Architecture	learnings/architecture.md
Conventions	learnings/conventions.md
Gotchas	learnings/gotchas.md
Integrations	learnings/integrations.md
Security	learnings/security.md
Testing	learnings/testing.md
Workflow	learnings/workflow.md

System Docs

• Architecture: ARCHITECTURE.md
• Operations: RUNBOOK.md
• Taxonomy: DOCS_TAXONOMY.md
• Quality: QUALITY_SCORE.md
• Feature Slicing: FEATURE_SLICING.md
• Contract: DOCS_CONTRACT.json

Directory Structure

docs/
├── README.md                    # This file (index)
├── ARCHITECTURE.md              # System design overview [reference]
├── RUNBOOK.md                   # Operations guide [how-to]
├── DOCS_TAXONOMY.md             # Where to put new docs [reference]
├── QUALITY_SCORE.md             # Domain quality grades [reference]
├── FEATURE_SLICING.md           # Feature slicing strategy [reference]
├── DOCS_CONTRACT.json           # Validation config [reference]
├── guides/                      # How-to guides [how-to]
│   └── README.md                # Guide index
├── design-docs/                 # Decision rationale [explanation]
│   ├── index.md                 # Design docs catalogue
│   ├── core-beliefs.md          # Agent-first principles
│   └── decisions/               # Architectural Decision Records
├── discovery/                   # Idea validation [explanation]
│   └── index.md                 # Discovery index
├── delivery-specs/              # Engineering handoff [reference]
│   └── index.md                 # Delivery specs index
├── exec-plans/                  # Work tracking [how-to]
│   ├── README.md                # Exec plans index
│   └── tech-debt-tracker.md     # Technical debt
├── exploration/                 # Ideas, scratchpad [exploration]
│   └── README.md                # Exploration index
├── learnings/                   # Durable patterns [reference]
│   ├── README.md                # Learnings index
│   ├── architecture.md          # Architecture learnings
│   ├── conventions.md           # Convention learnings
│   ├── gotchas.md               # Gotcha learnings
│   ├── integrations.md          # Integration learnings
│   ├── security.md              # Security learnings
│   ├── testing.md               # Testing learnings
│   ├── workflow.md              # Workflow learnings
│   └── archived/                # Overflow archive
│       └── README.md            # Archive policy
└── references/                  # External docs [reference]
    └── README.md                # External docs for agent context

Adding Documentation

If you need...	Create in...	Type
Step-by-step procedure	docs/guides/<topic>.md	how-to
Design for a feature	docs/design-docs/<feature>.md	explanation
External library docs	docs/references/<library>-llms.txt	reference