docs: add tutorial writing style resource #539

Affected Repositories

• PyAutoBrain (primary)

Work Classification

• Library-style development workflow for an organ repository.

Worktree root

• ~/Code/PyAutoLabs-wt/tutorial-documentation-style/

Branch Survey

No active Mind task claims PyAutoBrain. An older unregistered worktree exists at .worktrees/pyautodna-stack-management/PyAutoBrain on feature/pyautodna-stack-management; the human acknowledged it and this task will not touch it.

Suggested branch: feature/tutorial-documentation-style

Implementation Steps

1. Add skills/TUTORIAL_WRITING_STYLE.md with the approved voice, section arc, code narrative, audience adaptation, scientific distinctions, provenance safeguards, **🤖 Ask AI:** callouts, iterative editing contract and final checklist.
2. Include the established notebook-source conventions—opening __Contents__ and top-level """__Section__""" narrative docstrings—by pointing to the existing canonical format rather than creating a competing template.
3. Update skills/docs/docs.md so /docs loads WRITING_STYLE.md for READMEs/setup/web documentation, the tutorial guide for scientific scripts/notebooks/tutorials, and both for mixed work.
4. Update agents/faculties/review/AGENTS.md so tutorial-documentation diffs are checked against the new guide.
5. Add a focused test under tests/ that guards the /docs and review-faculty links to the canonical resource.
6. Run the targeted tests plus bin/install.sh --check-project-discovery PyAutoBrain and bin/install.sh --check-agents-surface.

Key Files

• skills/TUTORIAL_WRITING_STYLE.md — canonical scientific tutorial prose and editing guide.
• skills/docs/docs.md — callable /docs routing and application contract.
• agents/faculties/review/AGENTS.md — review-time enforcement.
• tests/test_docs_style_contract.py — single-source wiring contract.

Out of scope

• Editing the COSMOS-Web Ring notebook or assistant files themselves.
• Adding a new Brain conductor or faculty.
• Changing scientific claims, numerical values, code behaviour, links or citations in downstream tutorials.

This prompt describes the tone and style we hit when we made a good update to a python script / notebook documentation, in particular the first-AI-COSMOS-Ring example, can you turn this into a go to callable resource? Maybe use a skill but I think it could be part of PyAutoBrain as an agent or as part of its docs agent or something, which I think recently also got a github README.md style update:
Aim for the tone of a knowledgeable person guiding someone through a picture or experiment: direct, patient and precise, without sounding formal, promotional or childish.

Writing principles:

• Use plain language and short, connected paragraphs.
• Start with what the reader can see or do, then explain what it means.
• Introduce each technical term only when it becomes useful. Explain it in everyday language at first use.
• Prefer concrete descriptions: “50 smooth ellipses”, “the light left after subtracting the foreground galaxy”, “small differences consistent with noise”.
• Keep the science accurate. Simplify the explanation, not the underlying meaning.
• Avoid jargon about implementation when it does not help the reader understand the science.
• Avoid vague or distracting words such as “blob”, “speckles”, “payoff” and “headline number”.
• Avoid hype, rhetorical questions, forced analogies and repeated reassurance.
• Use British English.

For each section:

1. Orient the reader to the image, question or task.
2. Explain the relevant idea and why it matters.
3. Say what running the next code cell will do.
4. Explain what to look for in the output and how to interpret it.

For code:

• Keep the narrative focused on the scientific purpose.
• Put incidental implementation details in concise Python comments.
• When appropriate, tell readers which settings they can change and which they can leave alone.
• For experiments, explain the starting values, suggest specific changes, describe the expected effect and provide a clear way to reset.
• Distinguish loading or evaluating an existing model from fitting a new one.

Preserve important distinctions:

• Subtracting a foreground galaxy’s light is different from undoing the gravitational bending of the source’s light.
• A reconstruction is inferred from a model; it is not a direct photograph.
• A plausible measurement does not establish that a model fits well.
• A single best model does not by itself describe uncertainty.
• Attribute figures, data and models to their actual sources.

Adapt to the audience:

• For introductory tutorials, introduce fewer concepts and keep numerical methods out of the main narrative.
• For advanced tutorials, retain the necessary technical detail but explain its purpose before its mechanics.
• Do not remove useful detail merely to make the prose shorter.

Editing boundaries:

• Preserve scientific claims, numerical values, code behaviour, links, citations and required formatting unless I explicitly authorise changes.
• Flag scientific inaccuracies or misleading wording rather than silently preserving or replacing them.
• Do not invent provenance, results, performance claims or certainty.
• Respect any protected text blocks byte-for-byte.

Work iteratively:

• Review one coherent block at a time.
• Show proposed wording and briefly explain only the significant changes.
• Wait for my feedback before applying it.
• Carry agreed terminology and tone forward consistently.
• Edit canonical source files rather than generated notebooks or documentation, then run the project’s required regeneration and validation steps.

Ask AI / Gemini:

• At opportune moments in the example or tutorial, put an "Ask AI / Gemini:" thing in bold font with a suggested follow up
  question the reader can ask the AI.

Follow-up decisions

• All notebooks are AI material, so use **🤖 Ask AI:** everywhere and do not use a Gemini-specific label.
• Include the established opening __Contents__ and top-level """__Section__""" Python docstring format in the guidance by canonical reference.
• The skill-based /docs architecture and branch feature/tutorial-documentation-style are approved.