A skill that was too long to be read carefully

A two-thousand-word document describing this application’s architecture, which produced worse output than no document.

the failure mode, observed three times:

  the document says repositories, not models, in
  paragraph four of nine.

  the generated code used a model, and cited the
  document's paragraph seven — about module boundaries
  — as justification for where it put the file.

so the document was read, partially, and the part that
was applied was not the part that mattered.

split into six task-scoped documents of about 200
words. the failure stopped.

A long document produces confident output that follows some of it, which is worse than short output that follows none — the citation makes it look considered. This is a judgement rather than a measurement: three observations, no controlled comparison, and the change was cheap enough not to need one.