---
description: Standards for technical documentation and AI specification files. Covers documentation structure, update processes, language rules, and feedback integration.
alwaysApply: true
---

# Documentation Standards

## General Rules

- **ALWAYS WRITE IN ENGLISH**, including comments and explanations. This applies to creating new documentation, updating existing documentation, and inline code comments.

## Technical Documentation

Before making any commit, review which technical documentation should be updated.

### Update Process

1. Review all recent changes in the codebase
2. Identify which documentation files need updates:
   - Data model changes → `docs/specs/api-spec.yaml`
   - API changes → `docs/specs/api-spec.yaml`
   - Library/migration changes → `ai-specs/specs/*-standards.mdc`
   - UI component changes → `docs/specs/ui-components.md`
   - Configuration changes → `docs/project_notes/key_facts.md`
3. Update each affected documentation file in English
4. Maintain consistency with existing documentation structure
5. Verify all changes are accurately reflected

### Documentation Files

| File | Update When |
|------|-------------|
| `docs/specs/api-spec.yaml` | API endpoints or schemas change |
| `docs/specs/ui-components.md` | Component hierarchy or props change |
| `ai-specs/specs/backend-standards.mdc` | Backend patterns or deps change |
| `ai-specs/specs/frontend-standards.mdc` | Frontend patterns or deps change |
| `docs/project_notes/key_facts.md` | Configuration or infrastructure changes |
| `docs/project_notes/decisions.md` | Architectural decisions are made |
| `docs/project_notes/bugs.md` | Bugs are found and fixed |

## AI Specifications

AI specs are documents that instruct AI agents how to behave, plan, code, and document.

### Learning from Feedback

The AI should:
- Learn from user feedback, guidance, and suggestions
- Identify opportunities to improve existing development rules
- Keep assistance aligned with evolving project needs
- Incorporate feedback into the operational framework

### Update Protocol

When user feedback suggests a rule update:
1. Identify the specific rule or section to modify
2. Connect the proposed change to the user feedback
3. Propose the change and wait for explicit approval
4. Apply the modification only after approval
5. Confirm the update was made

### Anti-Patterns to Avoid

- **Skipping Approval**: Never apply rule changes without user review
- **Unlinked Proposals**: Always connect changes to specific feedback
- **Scope Creep**: Update one rule at a time, matching feedback scope
- **Unprompted Changes**: Only update rules when driven by feedback
- **Missing Confirmation**: Always notify after successful updates