+1

ArPiDev/AGENTS.md

··· 378 378 379 379 * **Validated done**: 380 380 * Pilot sets `Status: Done, Validated` and `Closed` timestamp. 381 381 + * Pilot ensures latest `Dev log` entries contain concrete causal why + evidence (not vague rationale). 381 382 * Pilot checks the story checkbox in `TASKS.md`. 382 383 * Pilot activates the next executable story automatically when one exists. 383 384 * For product changes, Pilot asks whether documentation follow-up is required in ArPiDoc and records the answer.

+7 -1

ArPiDev/definitions/agents/dev.md

··· 41 41 Record: 42 42 43 43 * what you changed 44 44 - * why (short, explicit, why it was done this way) 44 44 + * why (causal, specific, and evidence-backed: issue -> cause -> chosen fix -> tradeoff) 45 45 * commands you ran / checks you performed 46 46 * any local tradeoffs 47 47 * decision requests for the Pilot inside `Pilot exchange` (never write `DECISIONS.md` directly) ··· 51 51 All dev log entries must include a human-readable date and time using the format defined in `ArPiDev/definitions/artifacts/story.md`. 52 52 53 53 Do not write essays. 54 54 + 55 55 + Quality bar for `Why this way`: 56 56 + 57 57 + * Do not use vague reasons alone ("for clarity", "to avoid regression", "best practice"). 58 58 + * Tie each reason to a concrete symptom/risk and the verification result. 59 59 + * If you considered alternatives, mention the rejected option and why it was not chosen. 54 60 55 61 Status handling in the story: 56 62

+1

ArPiDev/definitions/agents/pilot.md

··· 116 116 1. **Done closure (finished + accepted)** 117 117 118 118 * Confirm acceptance with the `Acceptance` owner (default: user). 119 119 + * Verify the latest `Dev log` entries explain "why this way" with concrete cause/tradeoff/evidence; if too vague, request a rewrite before closure. 119 120 * Set `Status: Done, Validated` and add a `Closed` timestamp in the story file. 120 121 * Ensure the `Closed` timestamp uses the required human-readable format. 121 122 * Check the story checkbox in `TASKS.md`.

+11 -2

ArPiDev/definitions/artifacts/story.md

··· 78 78 - 2026-02-03 15h30m00s — Pilot -> Dev — Logged in `ArPiDev/DECISIONS.md`: <short decision> 79 79 80 80 ## Dev log 81 81 - - 2026-02-03 16h20m00s — <what changed> — <why this way> — <commands/tests> 81 81 + - 2026-02-03 16h20m00s — Change: <what changed> 82 82 + Why this way: 83 83 + - Observed issue: <concrete symptom or failing behavior> 84 84 + - Root cause: <what was actually wrong> 85 85 + - Chosen fix: <what was changed> 86 86 + - Why this option: <why this was selected over alternatives, with tradeoff> 87 87 + - Evidence: <how the change was validated> 88 88 + Commands/tests: <commands run + short result> 82 89 ``` 83 90 84 91 ## Notes ··· 101 108 * Story checkboxes in `TASKS.md` are checked only when status is `Done, Validated`. 102 109 * If acceptance is delegated to the Pilot, note it next to `Acceptance`. 103 110 * `Rationale` should be short, concrete, and tied to goals or constraints (not a long essay). 104 104 - * Every dev log entry must include an explicit “why” (why it was done this way, not just what was done). 111 111 + * Every dev log entry must include an explicit causal “why”: 112 112 + observed issue -> root cause -> chosen fix -> why this option -> evidence. 113 113 + * Generic lines like "to avoid regression" are insufficient unless tied to a specific risk and verification result.

+1

ArPiDoc/AGENTS.md

··· 387 387 388 388 * **Validated done**: 389 389 * Pilot sets `Status: Done, Validated` and `Closed` timestamp. 390 390 + * Pilot ensures latest `Doc log` entries contain concrete causal why + evidence (not vague rationale). 390 391 * Pilot checks the story checkbox in `TASKS.md`. 391 392 * Pilot activates the next executable story automatically when one exists. 392 393

+7 -1

ArPiDoc/definitions/agents/documenter.md

··· 63 63 Record: 64 64 65 65 * what you changed 66 66 - * why (short, explicit, why it was done this way) 66 66 + * why (causal, specific, and evidence-backed: gap -> source basis -> chosen structure -> tradeoff) 67 67 * commands you ran / checks you performed 68 68 * any local tradeoffs 69 69 * critical points documented (what is essential for users/operators/developers) ··· 73 73 All log entries must include a human-readable date and time using the format defined in `ArPiDoc/definitions/artifacts/story.md`. 74 74 75 75 Do not write essays. 76 76 + 77 77 + Quality bar for `Why this way`: 78 78 + 79 79 + * Do not use vague reasons alone ("for clarity", "more readable", "best practice"). 80 80 + * Tie each reason to a concrete audience need, source constraint, or user task. 81 81 + * If you considered alternatives, mention the rejected option and why it was not chosen. 76 82 77 83 Status handling in the story: 78 84

+1

ArPiDoc/definitions/agents/pilot.md

··· 103 103 1. **Done closure (finished + accepted)** 104 104 105 105 * Confirm acceptance with the `Acceptance` owner (default: user). 106 106 + * Verify the latest `Doc log` entries explain "why this way" with concrete audience need/source basis/tradeoff/evidence; if too vague, request a rewrite before closure. 106 107 * Set `Status: Done, Validated` and add a `Closed` timestamp in the story file. 107 108 * Ensure the `Closed` timestamp uses the required human-readable format. 108 109 * Check the story checkbox in `TASKS.md`.

+11 -2

ArPiDoc/definitions/artifacts/story.md

··· 79 79 - 2026-02-03 15h30m00s — Pilot -> Documenter — Logged in `ArPiDoc/DECISIONS.md`: <short decision> 80 80 81 81 ## Doc log 82 82 - - 2026-02-03 16h20m00s — <what changed> — <why this way> — <commands/tests> 82 82 + - 2026-02-03 16h20m00s — Change: <what changed> 83 83 + Why this way: 84 84 + - Observed gap: <concrete missing/unclear information or user pain> 85 85 + - Source basis: <sources used from code/artifacts> 86 86 + - Chosen structure/content: <what was written> 87 87 + - Why this option: <why this structure was selected over alternatives, with tradeoff> 88 88 + - Evidence: <how clarity/accuracy was validated> 89 89 + Commands/checks: <commands run + short result> 83 90 ``` 84 91 85 92 ## Notes ··· 102 109 * Story checkboxes in `TASKS.md` are checked only when status is `Done, Validated`. 103 110 * If acceptance is delegated to the Pilot, note it next to `Acceptance`. 104 111 * `Rationale` should be short, concrete, and tied to goals or constraints (not a long essay). 105 105 - * Every log entry must include an explicit “why” (why it was done this way, not just what was done). 112 112 + * Every doc log entry must include an explicit causal “why”: 113 113 + observed gap -> source basis -> chosen structure/content -> why this option -> evidence. 114 114 + * Generic lines like "for clarity" are insufficient unless tied to a concrete audience need and validation.