From 31457eac4f91838171a852b4f6868bad7109aac4 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Tue, 5 May 2026 17:29:29 -0700 Subject: [PATCH] fix: GSTACK REVIEW REPORT delete-then-append flow Replaces contradictory "replace it entirely" + "always last section / move if mid-file" bullets in scripts/resolvers/review.ts with a single delete-then-append rule. Adds Read-tool verification step so the agent self-checks before continuing. Affected SKILL.md files (regenerated): plan-ceo-review, plan-design-review, plan-devex-review, plan-eng-review, codex, devex-review. --- codex/SKILL.md | 32 +++++++++++++++++++++++--------- devex-review/SKILL.md | 32 +++++++++++++++++++++++--------- plan-ceo-review/SKILL.md | 32 +++++++++++++++++++++++--------- plan-design-review/SKILL.md | 32 +++++++++++++++++++++++--------- plan-devex-review/SKILL.md | 32 +++++++++++++++++++++++--------- plan-eng-review/SKILL.md | 32 +++++++++++++++++++++++--------- scripts/resolvers/review.ts | 32 +++++++++++++++++++++++--------- 7 files changed, 161 insertions(+), 63 deletions(-) diff --git a/codex/SKILL.md b/codex/SKILL.md index 44b5f0ed..e7cb13c3 100644 --- a/codex/SKILL.md +++ b/codex/SKILL.md @@ -1047,15 +1047,29 @@ Below the table, add these lines (omit any that are empty/not applicable): file you are allowed to edit in plan mode. The plan file review report is part of the plan's living status. -- Search the plan file for a \`## GSTACK REVIEW REPORT\` section **anywhere** in the file - (not just at the end — content may have been added after it). -- If found, **replace it** entirely using the Edit tool. Match from \`## GSTACK REVIEW REPORT\` - through either the next \`## \` heading or end of file, whichever comes first. This ensures - content added after the report section is preserved, not eaten. If the Edit fails - (e.g., concurrent edit changed the content), re-read the plan file and retry once. -- If no such section exists, **append it** to the end of the plan file. -- Always place it as the very last section in the plan file. If it was found mid-file, - move it: delete the old location and append at the end. +The report must always be the LAST section of the plan file — never mid-file. +Use a single delete-then-append flow: + +1. Read the plan file (Read tool) to see its full current content. Search the read + output for a \`## GSTACK REVIEW REPORT\` heading anywhere in the file. +2. If found, use the Edit tool to DELETE the entire existing section. Match from + \`## GSTACK REVIEW REPORT\` through either the next \`## \` heading or end of + file, whichever comes first. Replace with the empty string. This applies + regardless of where the section currently lives — mid-file deletion is + intentional, not a special case. If the Edit fails (e.g., concurrent edit + changed the content), re-read the plan file and retry once. +3. After the delete (or skipped, if no section existed), append the new + \`## GSTACK REVIEW REPORT\` section at the END of the file. Use the Edit + tool to match the file's current last paragraph and add the section after it, + or use Write to re-emit the whole file with the section at the end. +4. Verify with the Read tool that \`## GSTACK REVIEW REPORT\` is the last + \`## \` heading in the file before continuing. If it isn't, repeat steps + 2-3 once. + +Do NOT replace the section in place. The "replace mid-file" path is what allowed +prior versions to leave the report mid-file when an older report already lived +there — the user then sees a plan whose review report is not at the bottom and +(correctly) rejects it. --- diff --git a/devex-review/SKILL.md b/devex-review/SKILL.md index 53030027..3e00c49e 100644 --- a/devex-review/SKILL.md +++ b/devex-review/SKILL.md @@ -1153,15 +1153,29 @@ Below the table, add these lines (omit any that are empty/not applicable): file you are allowed to edit in plan mode. The plan file review report is part of the plan's living status. -- Search the plan file for a \`## GSTACK REVIEW REPORT\` section **anywhere** in the file - (not just at the end — content may have been added after it). -- If found, **replace it** entirely using the Edit tool. Match from \`## GSTACK REVIEW REPORT\` - through either the next \`## \` heading or end of file, whichever comes first. This ensures - content added after the report section is preserved, not eaten. If the Edit fails - (e.g., concurrent edit changed the content), re-read the plan file and retry once. -- If no such section exists, **append it** to the end of the plan file. -- Always place it as the very last section in the plan file. If it was found mid-file, - move it: delete the old location and append at the end. +The report must always be the LAST section of the plan file — never mid-file. +Use a single delete-then-append flow: + +1. Read the plan file (Read tool) to see its full current content. Search the read + output for a \`## GSTACK REVIEW REPORT\` heading anywhere in the file. +2. If found, use the Edit tool to DELETE the entire existing section. Match from + \`## GSTACK REVIEW REPORT\` through either the next \`## \` heading or end of + file, whichever comes first. Replace with the empty string. This applies + regardless of where the section currently lives — mid-file deletion is + intentional, not a special case. If the Edit fails (e.g., concurrent edit + changed the content), re-read the plan file and retry once. +3. After the delete (or skipped, if no section existed), append the new + \`## GSTACK REVIEW REPORT\` section at the END of the file. Use the Edit + tool to match the file's current last paragraph and add the section after it, + or use Write to re-emit the whole file with the section at the end. +4. Verify with the Read tool that \`## GSTACK REVIEW REPORT\` is the last + \`## \` heading in the file before continuing. If it isn't, repeat steps + 2-3 once. + +Do NOT replace the section in place. The "replace mid-file" path is what allowed +prior versions to leave the report mid-file when an older report already lived +there — the user then sees a plan whose review report is not at the bottom and +(correctly) rejects it. ## Capture Learnings diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index 42344be3..7e04c143 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -1958,15 +1958,29 @@ Below the table, add these lines (omit any that are empty/not applicable): file you are allowed to edit in plan mode. The plan file review report is part of the plan's living status. -- Search the plan file for a \`## GSTACK REVIEW REPORT\` section **anywhere** in the file - (not just at the end — content may have been added after it). -- If found, **replace it** entirely using the Edit tool. Match from \`## GSTACK REVIEW REPORT\` - through either the next \`## \` heading or end of file, whichever comes first. This ensures - content added after the report section is preserved, not eaten. If the Edit fails - (e.g., concurrent edit changed the content), re-read the plan file and retry once. -- If no such section exists, **append it** to the end of the plan file. -- Always place it as the very last section in the plan file. If it was found mid-file, - move it: delete the old location and append at the end. +The report must always be the LAST section of the plan file — never mid-file. +Use a single delete-then-append flow: + +1. Read the plan file (Read tool) to see its full current content. Search the read + output for a \`## GSTACK REVIEW REPORT\` heading anywhere in the file. +2. If found, use the Edit tool to DELETE the entire existing section. Match from + \`## GSTACK REVIEW REPORT\` through either the next \`## \` heading or end of + file, whichever comes first. Replace with the empty string. This applies + regardless of where the section currently lives — mid-file deletion is + intentional, not a special case. If the Edit fails (e.g., concurrent edit + changed the content), re-read the plan file and retry once. +3. After the delete (or skipped, if no section existed), append the new + \`## GSTACK REVIEW REPORT\` section at the END of the file. Use the Edit + tool to match the file's current last paragraph and add the section after it, + or use Write to re-emit the whole file with the section at the end. +4. Verify with the Read tool that \`## GSTACK REVIEW REPORT\` is the last + \`## \` heading in the file before continuing. If it isn't, repeat steps + 2-3 once. + +Do NOT replace the section in place. The "replace mid-file" path is what allowed +prior versions to leave the report mid-file when an older report already lived +there — the user then sees a plan whose review report is not at the bottom and +(correctly) rejects it. ## Next Steps — Review Chaining diff --git a/plan-design-review/SKILL.md b/plan-design-review/SKILL.md index d6ae7013..7cac8695 100644 --- a/plan-design-review/SKILL.md +++ b/plan-design-review/SKILL.md @@ -1722,15 +1722,29 @@ Below the table, add these lines (omit any that are empty/not applicable): file you are allowed to edit in plan mode. The plan file review report is part of the plan's living status. -- Search the plan file for a \`## GSTACK REVIEW REPORT\` section **anywhere** in the file - (not just at the end — content may have been added after it). -- If found, **replace it** entirely using the Edit tool. Match from \`## GSTACK REVIEW REPORT\` - through either the next \`## \` heading or end of file, whichever comes first. This ensures - content added after the report section is preserved, not eaten. If the Edit fails - (e.g., concurrent edit changed the content), re-read the plan file and retry once. -- If no such section exists, **append it** to the end of the plan file. -- Always place it as the very last section in the plan file. If it was found mid-file, - move it: delete the old location and append at the end. +The report must always be the LAST section of the plan file — never mid-file. +Use a single delete-then-append flow: + +1. Read the plan file (Read tool) to see its full current content. Search the read + output for a \`## GSTACK REVIEW REPORT\` heading anywhere in the file. +2. If found, use the Edit tool to DELETE the entire existing section. Match from + \`## GSTACK REVIEW REPORT\` through either the next \`## \` heading or end of + file, whichever comes first. Replace with the empty string. This applies + regardless of where the section currently lives — mid-file deletion is + intentional, not a special case. If the Edit fails (e.g., concurrent edit + changed the content), re-read the plan file and retry once. +3. After the delete (or skipped, if no section existed), append the new + \`## GSTACK REVIEW REPORT\` section at the END of the file. Use the Edit + tool to match the file's current last paragraph and add the section after it, + or use Write to re-emit the whole file with the section at the end. +4. Verify with the Read tool that \`## GSTACK REVIEW REPORT\` is the last + \`## \` heading in the file before continuing. If it isn't, repeat steps + 2-3 once. + +Do NOT replace the section in place. The "replace mid-file" path is what allowed +prior versions to leave the report mid-file when an older report already lived +there — the user then sees a plan whose review report is not at the bottom and +(correctly) rejects it. ## Capture Learnings diff --git a/plan-devex-review/SKILL.md b/plan-devex-review/SKILL.md index 22c508b3..d61828ed 100644 --- a/plan-devex-review/SKILL.md +++ b/plan-devex-review/SKILL.md @@ -1926,15 +1926,29 @@ Below the table, add these lines (omit any that are empty/not applicable): file you are allowed to edit in plan mode. The plan file review report is part of the plan's living status. -- Search the plan file for a \`## GSTACK REVIEW REPORT\` section **anywhere** in the file - (not just at the end — content may have been added after it). -- If found, **replace it** entirely using the Edit tool. Match from \`## GSTACK REVIEW REPORT\` - through either the next \`## \` heading or end of file, whichever comes first. This ensures - content added after the report section is preserved, not eaten. If the Edit fails - (e.g., concurrent edit changed the content), re-read the plan file and retry once. -- If no such section exists, **append it** to the end of the plan file. -- Always place it as the very last section in the plan file. If it was found mid-file, - move it: delete the old location and append at the end. +The report must always be the LAST section of the plan file — never mid-file. +Use a single delete-then-append flow: + +1. Read the plan file (Read tool) to see its full current content. Search the read + output for a \`## GSTACK REVIEW REPORT\` heading anywhere in the file. +2. If found, use the Edit tool to DELETE the entire existing section. Match from + \`## GSTACK REVIEW REPORT\` through either the next \`## \` heading or end of + file, whichever comes first. Replace with the empty string. This applies + regardless of where the section currently lives — mid-file deletion is + intentional, not a special case. If the Edit fails (e.g., concurrent edit + changed the content), re-read the plan file and retry once. +3. After the delete (or skipped, if no section existed), append the new + \`## GSTACK REVIEW REPORT\` section at the END of the file. Use the Edit + tool to match the file's current last paragraph and add the section after it, + or use Write to re-emit the whole file with the section at the end. +4. Verify with the Read tool that \`## GSTACK REVIEW REPORT\` is the last + \`## \` heading in the file before continuing. If it isn't, repeat steps + 2-3 once. + +Do NOT replace the section in place. The "replace mid-file" path is what allowed +prior versions to leave the report mid-file when an older report already lived +there — the user then sees a plan whose review report is not at the bottom and +(correctly) rejects it. ## Capture Learnings diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index 9d9e623f..bed2b2ee 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -1537,15 +1537,29 @@ Below the table, add these lines (omit any that are empty/not applicable): file you are allowed to edit in plan mode. The plan file review report is part of the plan's living status. -- Search the plan file for a \`## GSTACK REVIEW REPORT\` section **anywhere** in the file - (not just at the end — content may have been added after it). -- If found, **replace it** entirely using the Edit tool. Match from \`## GSTACK REVIEW REPORT\` - through either the next \`## \` heading or end of file, whichever comes first. This ensures - content added after the report section is preserved, not eaten. If the Edit fails - (e.g., concurrent edit changed the content), re-read the plan file and retry once. -- If no such section exists, **append it** to the end of the plan file. -- Always place it as the very last section in the plan file. If it was found mid-file, - move it: delete the old location and append at the end. +The report must always be the LAST section of the plan file — never mid-file. +Use a single delete-then-append flow: + +1. Read the plan file (Read tool) to see its full current content. Search the read + output for a \`## GSTACK REVIEW REPORT\` heading anywhere in the file. +2. If found, use the Edit tool to DELETE the entire existing section. Match from + \`## GSTACK REVIEW REPORT\` through either the next \`## \` heading or end of + file, whichever comes first. Replace with the empty string. This applies + regardless of where the section currently lives — mid-file deletion is + intentional, not a special case. If the Edit fails (e.g., concurrent edit + changed the content), re-read the plan file and retry once. +3. After the delete (or skipped, if no section existed), append the new + \`## GSTACK REVIEW REPORT\` section at the END of the file. Use the Edit + tool to match the file's current last paragraph and add the section after it, + or use Write to re-emit the whole file with the section at the end. +4. Verify with the Read tool that \`## GSTACK REVIEW REPORT\` is the last + \`## \` heading in the file before continuing. If it isn't, repeat steps + 2-3 once. + +Do NOT replace the section in place. The "replace mid-file" path is what allowed +prior versions to leave the report mid-file when an older report already lived +there — the user then sees a plan whose review report is not at the bottom and +(correctly) rejects it. ## Capture Learnings diff --git a/scripts/resolvers/review.ts b/scripts/resolvers/review.ts index 53c7b08d..e9a8d3e5 100644 --- a/scripts/resolvers/review.ts +++ b/scripts/resolvers/review.ts @@ -133,15 +133,29 @@ Below the table, add these lines (omit any that are empty/not applicable): file you are allowed to edit in plan mode. The plan file review report is part of the plan's living status. -- Search the plan file for a \\\`## GSTACK REVIEW REPORT\\\` section **anywhere** in the file - (not just at the end — content may have been added after it). -- If found, **replace it** entirely using the Edit tool. Match from \\\`## GSTACK REVIEW REPORT\\\` - through either the next \\\`## \\\` heading or end of file, whichever comes first. This ensures - content added after the report section is preserved, not eaten. If the Edit fails - (e.g., concurrent edit changed the content), re-read the plan file and retry once. -- If no such section exists, **append it** to the end of the plan file. -- Always place it as the very last section in the plan file. If it was found mid-file, - move it: delete the old location and append at the end.`; +The report must always be the LAST section of the plan file — never mid-file. +Use a single delete-then-append flow: + +1. Read the plan file (Read tool) to see its full current content. Search the read + output for a \\\`## GSTACK REVIEW REPORT\\\` heading anywhere in the file. +2. If found, use the Edit tool to DELETE the entire existing section. Match from + \\\`## GSTACK REVIEW REPORT\\\` through either the next \\\`## \\\` heading or end of + file, whichever comes first. Replace with the empty string. This applies + regardless of where the section currently lives — mid-file deletion is + intentional, not a special case. If the Edit fails (e.g., concurrent edit + changed the content), re-read the plan file and retry once. +3. After the delete (or skipped, if no section existed), append the new + \\\`## GSTACK REVIEW REPORT\\\` section at the END of the file. Use the Edit + tool to match the file's current last paragraph and add the section after it, + or use Write to re-emit the whole file with the section at the end. +4. Verify with the Read tool that \\\`## GSTACK REVIEW REPORT\\\` is the last + \\\`## \\\` heading in the file before continuing. If it isn't, repeat steps + 2-3 once. + +Do NOT replace the section in place. The "replace mid-file" path is what allowed +prior versions to leave the report mid-file when an older report already lived +there — the user then sees a plan whose review report is not at the bottom and +(correctly) rejects it.`; } export function generateSpecReviewLoop(_ctx: TemplateContext): string {