mcollina/documentation
Creates, structures, and reviews technical documentation following the Diátaxis framework (tutorials, how-to guides, reference, and explanation pages). Use when a user needs to write or reorganize docs, structure a tutorial vs. a how-to guide, build reference docs or API documentation, create explanation pages, choose between Diátaxis documentation types, or improve existing documentation structure. Trigger terms include: documentation structure, Diátaxis, tutorials vs how-to guides, organize docs, user guide, reference docs, technical writing.
91
87%
Does it follow best practices?
Impact
96%
1.11xAverage score across 5 eval scenarios
Passed
No known issues
task.mdevals/scenario-1/
Write a Conceptual Overview of Database Indexing
Problem/Feature Description
A backend engineering team is onboarding several mid-level developers who have SQL experience but a shallow understanding of what database indexes actually are, how the database engine uses them, and — critically — why indexes can sometimes hurt performance rather than help it. The team lead keeps having to explain these concepts during code reviews and wants a well-written documentation page they can point developers to instead.
The team lead is explicit: they do NOT want step-by-step instructions for creating indexes — there are plenty of those online. They want something that builds genuine understanding: why indexes exist in the first place, how the database engine decides to use them, and when a developer should think twice before adding one. After reading it, a developer should be able to reason about index choices in unfamiliar situations, not just follow a recipe.
Output Specification
Produce a Markdown file named explanation.md that gives developers a conceptual understanding of database indexing. The document should be for PostgreSQL (but avoid step-by-step SQL commands as the primary content). You may use brief SQL snippets as illustrations, but the document should be primarily prose that explains concepts, trade-offs, and design rationale.
Name the output file explanation.md.