diff --git a/skills/TRIP-1-plan/SKILL.md b/skills/TRIP-1-plan/SKILL.md index eddcc82..2bf741a 100644 --- a/skills/TRIP-1-plan/SKILL.md +++ b/skills/TRIP-1-plan/SKILL.md @@ -13,6 +13,7 @@ You are now in **planning mode** for **[PROJECT_NAME]**. Before creating any plan, you MUST read ALL THE LINES of: 1. @docs/ARCHI.md - Understand current system architecture +2. [ADAPT_TO_PROJECT: optional — list additional living docs a plan must respect (e.g. an operations manual, a public API contract), each with the condition under which it must be read ("only if the feature touches X"). Remove this line if the project has none.] ## Your Task @@ -119,6 +120,14 @@ Depending on the feature (major, minor, patch), propose a new version using SemV [2-5 bullets: which existing tests the change affects, what new logic will need tests, whether an integration/E2E check applies. No test code — the TRIP-2 testing gate consumes this section.] +## Documentation Impact + +[Mandatory. List every document OUTSIDE the TRIP docs that this feature will leave outdated, with one line each on what becomes stale. Always evaluate these candidates: + +[ADAPT_TO_PROJECT: During Init, replace with the project's actual living docs — every non-TRIP document that code changes can leave stale. Typical candidates: `README.md` (quick start, repo structure tree, command reference), module/subdirectory READMEs, operations or user manuals, reference `.md` specs living next to the code, contributor guides (`CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`). One bullet per doc with when it's affected.] + +If none are affected, write "None". The TRIP-3 Documentation Sync step consumes this section before the release commit.] + ## To-dos ### Phase 1: [Phase Name] (if multiple phases are needed) or simply skip title if only one phase is needed diff --git a/skills/TRIP-3-release/SKILL.md b/skills/TRIP-3-release/SKILL.md index d854af0..75b4e2f 100644 --- a/skills/TRIP-3-release/SKILL.md +++ b/skills/TRIP-3-release/SKILL.md @@ -43,9 +43,11 @@ Any failure blocks the release — fix or return to `TRIP-2-implement` first. Run this command to get date and project week: ```bash -date '+%d-%m-%Y %H:%M' && echo "Project week: $(( ( $(date +%s) - $(date -d '[WEEK_ANCHOR_DATE]' +%s) ) / 604800 + 1 ))" +date '+%d-%m-%Y %H:%M' && python3 -c "from datetime import date; print('Project week:', (date.today() - date.fromisoformat('[WEEK_ANCHOR_DATE]')).days // 7 + 1)" ``` +(Week anchor: the Monday of the week TRIP Init was run. Python is used instead of `date -d` because macOS BSD `date` doesn't support it.) + Use the project week in all subsequent steps. ## Step 2: Version Update @@ -133,6 +135,17 @@ Create `docs/5-tuto/tuto_x.y.z.md` explaining the core principle. Update `README.md` with the new version number. Also update relevant sections whenever needed. +## Step 9: Documentation Sync + +Keep the pre-existing (non-TRIP) documentation aligned with the code: + +1. Read the plan's **Documentation Impact** section. +2. Contrast it with the **actual diff** of the release (`git diff [MAIN_BRANCH]...HEAD` or equivalent) — the plan may have fallen short; a doc affected by the real changes must be synced even if the plan didn't list it. +3. Update every affected document. **Factual corrections only**: commands, paths, build targets, script/table entries, cadences, config/env vars, structure trees. It is **forbidden** to touch the voice, tone, or strategic/editorial content of these documents. +4. The updated files are included in the release commit (Step 10) — never a separate commit. + +If the plan says "None" and the diff confirms it, skip with a one-line note. + --- After completing all documentation steps, **use the `AskUserQuestion` tool** to ask: @@ -142,7 +155,7 @@ After completing all documentation steps, **use the `AskUserQuestion` tool** to **ONLY after user selects "Yes"**, proceed: -## Step 9: Commit +## Step 10: Commit ```bash git add -A && git commit -m "" @@ -150,13 +163,13 @@ git add -A && git commit -m "" **Important**: Only use the commit message. Do NOT add Co-Authored-By or any other trailer. -## Step 10: Tag +## Step 11: Tag ```bash git tag vx.y.z ``` -## Step 11: Merge (fast-forward) +## Step 12: Merge (fast-forward) Merge the feature branch back into the main branch, keeping a single clean linear history: @@ -168,7 +181,7 @@ git branch -d If `--ff-only` fails, the main branch moved during implementation — rebase the feature branch onto it, then retry. **Never create a merge commit.** -## Step 12: Push +## Step 13: Push **Use the `AskUserQuestion` tool** to ask: diff --git a/skills/TRIP-init/SKILL.md b/skills/TRIP-init/SKILL.md index a8286aa..1349d4e 100644 --- a/skills/TRIP-init/SKILL.md +++ b/skills/TRIP-init/SKILL.md @@ -469,7 +469,7 @@ After user validation, update the other TRIP skill files based on the **actual c ### Skills to Update: -1. **`TRIP-1-plan`** - Technical considerations, guidance sections +1. **`TRIP-1-plan`** - Technical considerations, guidance sections, documentation impact candidates 2. **`TRIP-2-implement`** - Testing gate commands 3. **`TRIP-3-release`** - Version file, week offset, tutorials 4. **`TRIP-review`** - `checklist.md` and `cr-template.md` adapted to actual architecture @@ -616,7 +616,21 @@ Required analysis: _These are examples. Create guidance sections based on what's actually in ARCHI.md - the major patterns, layers, and component types specific to this project._ -**C. Custom Plan Sections** +**C. Documentation Impact Candidates** + +Replace the `[ADAPT_TO_PROJECT]` marker inside the plan template's **Documentation Impact** section with the project's actual living documentation — every non-TRIP document that code changes can leave stale, one bullet per doc with when it's affected. Draw from what Phase 2 discovered: + +- `README.md` — quick start, repo structure tree, command reference +- Module/subdirectory READMEs +- Operations or user manuals +- Reference `.md` specs living next to the code +- Contributor guides (`CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`) + +This list is what makes the TRIP-3 Documentation Sync step effective — a doc missing here tends to drift silently. + +Also resolve the `[ADAPT_TO_PROJECT]` marker in the **Prerequisites** list at the top of `TRIP-1-plan`: if the project has living docs a plan must respect beyond ARCHI.md (e.g. an operations manual), list them with the condition under which they must be read; otherwise delete that line. + +**D. Custom Plan Sections** **Use the `AskUserQuestion` tool** to ask: @@ -645,15 +659,15 @@ Update Step 2 to reference the actual version file: **B. Week Anchor** -The week Init is run becomes **Week 1** of the project. Capture the anchor date (Monday of the current week) and update the week formula in `TRIP-2-implement`. +The week Init is run becomes **Week 1** of the project. Capture the anchor date (Monday of the current week) and update the week formula in `TRIP-3-release`. Run this to get the anchor date: ```bash -date -d "last monday" '+%Y-%m-%d' # If today is Monday, use: date '+%Y-%m-%d' +python3 -c "from datetime import date, timedelta; t = date.today(); print(t - timedelta(days=t.weekday()))" ``` -Then replace the `[WEEK_ANCHOR_DATE]` placeholder in `TRIP-3-release` Step 1 with the actual date. The formula counts elapsed weeks from that fixed date, so it works across year boundaries indefinitely. +Then replace the `[WEEK_ANCHOR_DATE]` placeholder in `TRIP-3-release` Step 1 with the actual date (ISO format, `YYYY-MM-DD` — the formula parses it with `date.fromisoformat`). The formula counts elapsed weeks from that fixed date, so it works across year boundaries indefinitely, and both this command and the formula use Python instead of `date -d`, so they run identically on GNU/Linux and macOS (BSD `date`). **C. Tutorial Generation** @@ -687,7 +701,7 @@ Then replace the `[WEEK_ANCHOR_DATE]` placeholder in `TRIP-3-release` Step 1 wit Then update the `[TUTORIAL_STEP]` block in `TRIP-3-release` with the user's context: ```markdown -### Step 7: Tutorial +### Step 8: Tutorial Create `docs/5-tuto/tuto_x.y.z.md` explaining the core principle. @@ -703,8 +717,13 @@ Create `docs/5-tuto/tuto_x.y.z.md` explaining the core principle. **IMPORTANT — Renumber subsequent steps**: After uncommenting the Tutorial as Step 8, renumber the steps that follow: - Step 8: README Update → **Step 9**: README Update -- Step 9: Commit → **Step 10**: Commit -- Step 10: Tag → **Step 11**: Tag +- Step 9: Documentation Sync → **Step 10**: Documentation Sync +- Step 10: Commit → **Step 11**: Commit +- Step 11: Tag → **Step 12**: Tag +- Step 12: Merge (fast-forward) → **Step 13**: Merge (fast-forward) +- Step 13: Push → **Step 14**: Push + +Also update the cross-reference inside Documentation Sync — "included in the release commit (Step 10)" becomes "(Step 11)". **D. Codex Review Test Commands** @@ -1011,6 +1030,8 @@ Update: Technology Stack, and any affected architectural sections - [ ] `[PROJECT_NAME]` placeholder replaced in all skills - [ ] `TRIP-1-plan`: `[ADAPT_TO_PROJECT]` markers replaced with actual technical considerations - [ ] `TRIP-1-plan`: Guidance sections replaced with project-specific patterns + - [ ] `TRIP-1-plan`: Documentation Impact candidates replaced with the project's actual living docs + - [ ] `TRIP-1-plan`: Prerequisites `[ADAPT_TO_PROJECT]` line resolved (project docs listed, or line deleted) - [ ] `TRIP-1-plan`: Custom plan sections added (if user requested) - [ ] `TRIP-2-implement`: Testing gate commands (`[LINT_COMMAND]`, `[TYPECHECK_COMMAND]`, `[TEST_COMMAND]`) replaced with actual commands - [ ] `TRIP-3-release`: `[VERSION_FILE]` placeholder replaced