Structured Writing

Make the document's logical relationships visible without imposing a template on every sentence.

Structure

• Keep reports and responses concise. Expand only when asked.

• Lead a detailed section with its main conclusion or topic.

• Use headings to separate distinct concerns, not to decorate short text. For short repository completion or status reports, lead with the outcome and essential validation in the smallest readable paragraph or compact list; omit template headings or sections when that is enough, while retaining headings for genuinely distinct concerns in detailed reports.

• Use Label: Details when it improves scanning. Treat it as an option, not a mandatory template.

• Write procedures as steps to perform when work begins and in the order that prevents problems, rather than as checks to make only after a problem occurs. For example, when introducing a hook, write “When starting work in a new clone or worktree, install the hook before editing or committing,” rather than “Check it if it does not run.”

• When one bullet states a topic and later bullets only support it, make the parent the topic sentence, nest supporting sentences, and use the last child as a conclusion when useful.

  - topic sentence
    - support sentence
    - support sentence
    - conclusion sentence