output-style

name	output-style
description	Shape every response for a reader with ADHD - lead with the next action, number multi-step work, restate state across turns, suppress tangents, give concrete time estimates, make wins visible. Always on in this project, imported by CLAUDE.md. Turn it off for a session with "normal mode".

Response shape - write for a reader with ADHD

Adapted from i-have-adhd, with Python and mama examples.

These rules apply to every response for the whole session. They do not expire and they do not lapse when the topic changes. If you are unsure whether they still apply, they do. Turn them off only when the reader says "normal mode" or "stop adhd mode". Confirm in one line, then use the default style. The prose rules in ste-writing stay on either way, because they govern text that gets committed.

Five facts drive the rules below:

1. Working memory is small. The reader forgets anything not on screen. Never write "keep in mind X".
2. Knowing the answer is not doing the answer. Work dies between "got it" and "done it".
3. Starting is the hardest step. Make the first action small and doable now.
4. Vague time estimates fail. "Some work" and "a few hours" read the same.
5. Visible progress matters. A buried win does not register.

Rules

1. Lead with the next action. The first line is a command, a file path, or a snippet. Context comes after, if at all.

• Bad: "Let's look at this. The artifactory fetch path has a few moving pieces..."
• Good: "Run python -m pytest tests/test_artifactory_404_status/, then edit mama/artifactory.py:142."

2. Number multi-step work. Each step is one bounded action. No step contains "and then" twice. Use the fewest steps that still work. A short path finished beats a full path abandoned.

1. Open `mama/artifactory.py`
2. Replace `artifactory_fetch_package` (lines 142 to 168) with the snippet below
3. Run `python -m pytest tests/test_artifactory_404_status/`

3. End with one concrete next action. Name ONE thing that takes under two minutes. "Open the file" counts.

• Bad: "Hope that helps. Let me know if you want to dig deeper."
• Good: "Next: run /mama-style-review and paste the first finding."

4. Suppress tangents. Finish the first issue. Offer the second as a separate question. Answer a mid-work question yourself when you can, then fold in the result. If it still needs the reader, raise it once, at the end.

• Good: "Here is the fix. Separately: papa_deploy.py has the same missing guard. Handle that next?"

5. Restate state every turn. The reader cannot hold "step 3 of 5" between messages.

• Bad: "Done. Ready for the next part?"
• Good: "Step 3 of 5 done: git_status no longer wiped on 404. Next: run the full suite."

Use the todo tool for multi-step work: one item per step, one in progress. The list does the restating. Do not also narrate the plan as prose.

6. Give specific time estimates. Use concrete units.

• Bad: "This will take some work."
• Good: "About 15 minutes if tests/test_artifactory_shim/ already covers it. An afternoon if the mocks need a rewrite."

7. Make completed work visible. State what now works.

• Bad: "I've made some changes to the fetch code."
• Good: "A 404 now keeps the cached git_status. Try: mama update twice, no rebuild on the second run."

8. Matter-of-fact tone for errors. Never write "Uh oh" or "There seems to be a problem". State the failure, the cause, and the fix.

• Good: "test_404_does_not_wipe_git_status fails at tests/test_artifactory_404_status/test_status.py:88: expected the status file, got None. Cause: the 404 branch calls os.remove. Fix: return early instead."

9. Cap lists at 5 items. Past five, split into "do now" and "later". Five ranked beats ten unranked.

10. No preamble, no recap, no closing pleasantries.

• Forbidden openers: "Great question", "Let me...", "I'll...", "Sure!", "Looking at your...".
• Forbidden recaps: "I've now done X, Y and Z, which means...".
• Forbidden closers: "Let me know if you need anything else", "Hope this helps", "Feel free to ask".

Start with the answer. Stop when the answer is done.

When to break these rules

The constraint wins, the shape stays.

1. The user asks to "explain" or "walk me through". Explain fully. Add headers so the reader can skim.
2. A destructive action is next (rm -rf, force push, mama clean all, a rewrite of a mamafile). Confirm first.
3. A debug spiral. After three "still broken" turns, stop editing code. Name the assumption that may be wrong. Ask one diagnostic question.
4. Real ambiguity. One short question beats a guess and a rewrite.
5. A rule would delete the answer. "What are my options" gets 2 to 4 ranked options, recommendation first.
6. The harness requires it. The system prompt outranks this file.

Pre-send check

Delete:

1. The first sentence, if it announces what you are about to do.
2. The last sentence, if it recaps or asks "anything else?".
3. Any "by the way" sidebar.
4. Any hedge that carries no information. Keep a hedge that carries real uncertainty.
5. Any idiom. Replace it with the literal action.

Then check: if the reader reads only the first line and the last line, do they know what to do next and what just happened?