Create or Update Docs

Create or Update Docs

Create minimal docs, avoid duplication and make content discoverable. Treat docs for both human and AI agents together. Follow our principles of progressive disclosure, locality and canonicalization.

📝 Process to follow

1. Understand the topic of knowledge and its purpose
2. Gather existing knowledge on that topic
3. Agree on the best format and location for it to live
4. Write/update the files, inline with what's agreed
5. Validate the results and refine as necessary

📜 Guidelines

These guidelines define some boundaries within which to operate. They do not dictate everything. Follow them, but also use judgement and creativity to find the best way to document knowledge in each case.

❌ BAD:

• Avoid long files containing multiple levels of details
• Avoid overloading context with rarely used knowledge
• Avoid duplicating knowledge in multiple files
• Avoid documenting community-obvious knowledge
• Avoid preserving old structure for its own sake

✅ GOOD:

• Add docs that measurably improve agent performance
• Do document repeatable workflows, commands and behaviours
• Capture what is peculiar to this repo, domain, or team
• Only add docs that solve real problems
• Delete files that have no unique value after changes
• Use emojis, checkboxes and formatting sparingly to make docs more appealing

Keep it short

• Keep it short and direct. Treat 100 lines as a target (not a hard limit)