From 93d9a40c679d3a169348610846d1672e1a7c3207 Mon Sep 17 00:00:00 2001 From: Sebastien Taggart Date: Fri, 24 Apr 2026 09:09:55 -0400 Subject: [PATCH] Replace 'Resuming work' comment with conditional investigation findings gate and simplify skill rubrics --- .agents/skills/start/SKILL.md | 63 +++++++++++++---------- .agents/skills/submit-for-review/SKILL.md | 8 +-- .claude/commands/start.md | 63 +++++++++++++---------- .claude/commands/submit-for-review.md | 8 +-- .cursor/rules/start.mdc | 63 +++++++++++++---------- .cursor/rules/submit-for-review.mdc | 8 +-- .gemini/skills/start/SKILL.md | 63 +++++++++++++---------- .gemini/skills/submit-for-review/SKILL.md | 8 +-- skills/start.md | 61 ++++++++++++---------- skills/submit-for-review.md | 6 +-- 10 files changed, 188 insertions(+), 163 deletions(-) diff --git a/.agents/skills/start/SKILL.md b/.agents/skills/start/SKILL.md index a1922d0..902a15f 100644 --- a/.agents/skills/start/SKILL.md +++ b/.agents/skills/start/SKILL.md @@ -115,12 +115,7 @@ Stop. Wait for the user to respond. The friendly text question is required regardless of harness mode. If your harness is currently in a preview / plan / dry-run mode where you cannot passively stop and wait (and must instead invoke the harness's own approval mechanism), still include the text question in your response. The harness's approval UI mediates the wait, but it is not a substitute for the question itself. Users expect to see the consistent text language across all modes; do not silently swap it for the harness's UI. -**Intent classification (not keyword matching):** - -- **Affirmative with no conditions** ("go", "yes", "looks good", "let's do it") → continue to Step 3. -- **Affirmative with conditions** ("go, but first change X", "yes but can we also...") → treat as discussion. Address the conditions, revise the approach if needed, then re-ask. -- **Questions or pushback** ("what about...", "I'm not sure about...", any adjustment) → discuss, revise approach, re-ask. -- **Abandonment** ("never mind", "not now", "stop") → stop. Nothing to clean up. +Proceed only on unconditional approval. If the user's response includes conditions, questions, or adjustments, treat it as discussion — address their input and re-ask. If the user abandons ("never mind", "stop"), stop — nothing to clean up. ### Step 3 — Create GitHub Issue @@ -176,12 +171,6 @@ Use the labels and milestone you already resolved in the Parsing section (before All five sections are required. Write for a non-developer audience — no code, no file paths. Acceptance Criteria must be concrete and verifiable (not vague goals). -**Complexity scale guidance (for agent use only — do not include the scale definition in the issue body):** -- **trivial** — single obvious check (e.g. color change, label text, toggle visibility) -- **moderate** — a few scenarios to verify, minor setup needed (e.g. form validation, a new UI component with a couple of states) -- **significant** — many scenarios, data setup, or cross-feature impact (e.g. multi-step workflow, permission changes across roles) -- **extensive** — complex data flows, integration testing, or edge cases spanning multiple areas (e.g. data import/export mapping, API contract changes consumed by multiple clients) - **Title rules:** - ✅ `Fix 'Contact Us' footer link pointing to 404 instead of /contact-us` - ❌ `Fix broken link` @@ -261,15 +250,41 @@ Tell the user: Ask: **"Does this match your understanding? Type `go` to start coding, or share any questions/adjustments first."** -**Intent classification (not keyword matching):** +Proceed only on unconditional approval. If the user's response includes conditions, questions, or adjustments, treat it as discussion — address their input and re-ask. If the user wants a fresh start, restart as Case A. If the user abandons, stop — nothing to clean up. + +### Step 3 — Investigation findings (conditional) + +If the investigation in Steps 1–2 revealed anything that isn't already stated or implied by the issue body — a root cause correction, a related side-effect, a project-wide gotcha — present the findings. If the investigation simply confirmed the ticket, skip this step silently and proceed to Step 4. + +Create a temp directory for this invocation: + +```bash +mkdir -p /tmp/CodeCannon && mktemp -d /tmp/CodeCannon/XXXXXX +``` + +Present numbered findings: -- **Affirmative with no conditions** ("go", "yes", "continue", "looks right") → proceed to Step 3. -- **Affirmative with conditions** ("go, but first...", "yes but let's also...") → treat as discussion. Address the conditions, then re-ask. -- **Questions or discussion** ("what about...", "can we change...", any adjustment) → discuss, then re-ask. -- **Fresh start** ("open a new one", "start fresh", "new ticket") → restart as Case A with a new description. -- **Abandonment** ("never mind", "not now", "stop") → stop. Nothing to clean up. +> The investigation surfaced the following: +> +> 1. +> 2. +> +> **post** as a comment to the ticket, or **skip** to continue. -### Step 3 — Check out branch +- `post` → use your file-writing tool (not Bash) to create `/investigation_comment.md`: + ```markdown + ## Investigation Findings + + - + - + ``` + Then post it: + ```bash + gh issue comment --body-file /investigation_comment.md + ``` +- `skip` → proceed silently. + +### Step 4 — Check out branch Ensure the base branch is up-to-date before branching: @@ -291,13 +306,7 @@ Verify: git branch --show-current ``` -Post a resumption comment: - -```bash -gh issue comment --body "Resuming work. " -``` - -### Step 4 — Write the code +### Step 5 — Write the code Continue from where work left off. Do NOT commit. @@ -315,4 +324,4 @@ When done, say: **"The code is ready for review. Please run `make dev` and test - The issue is assigned to `@me` at creation. If you are creating a ticket on someone else's behalf, remove the assignee after creation with `gh issue edit --remove-assignee @me`. - Apply resolved labels and milestone to every new issue. Label resolution order: per-invocation flag → pool selection from `bug, documentation, enhancement, chore` → omit `--label` entirely. Never apply a label outside `bug, documentation, enhancement, chore`. - Milestone resolution order: per-invocation flag → auto-detected from GitHub open milestones. Never prompt for a milestone more than once per invocation. - + diff --git a/.agents/skills/submit-for-review/SKILL.md b/.agents/skills/submit-for-review/SKILL.md index d3a5d30..eea5728 100644 --- a/.agents/skills/submit-for-review/SKILL.md +++ b/.agents/skills/submit-for-review/SKILL.md @@ -279,11 +279,7 @@ Then post it (do NOT use `--body` or heredocs): gh issue comment --body-file /resolution_comment.md ``` -**Resolution writing rules:** -- Write for PMs and BAs, not developers. Describe the *outcome*, not the implementation. -- Reference the original problem from the issue body so the resolution reads as a direct answer to it. -- Keep it to 1-3 sentences. If one sentence covers it, don't pad. -- Use the unqualified `#N` form for the PR reference. +Use the unqualified `#N` form for the PR reference (not `owner/repo#N`). Report success based on mode: "PR merged. Issues stay open until testing confirms the fix. Run `make deploy-preview` when ready to deploy to preview." @@ -354,4 +350,4 @@ If a single `gh issue create` call fails, report the failure for that finding an - `/submit-for-review` merges only to `dev` — never directly to `main`. - If `make merge` fails for any reason, report it and stop — do not attempt workarounds. - The follow-up issue offer in Step 9 runs only after a successful merge and only when the review produced non-blocking findings. Never prompt the user for follow-ups when the review blocked the merge — those findings should be fixed, not ticketed. - + diff --git a/.claude/commands/start.md b/.claude/commands/start.md index f81ce74..d73956b 100644 --- a/.claude/commands/start.md +++ b/.claude/commands/start.md @@ -110,12 +110,7 @@ Stop. Wait for the user to respond. The friendly text question is required regardless of harness mode. If your harness is currently in a preview / plan / dry-run mode where you cannot passively stop and wait (and must instead invoke the harness's own approval mechanism), still include the text question in your response. The harness's approval UI mediates the wait, but it is not a substitute for the question itself. Users expect to see the consistent text language across all modes; do not silently swap it for the harness's UI. -**Intent classification (not keyword matching):** - -- **Affirmative with no conditions** ("go", "yes", "looks good", "let's do it") → continue to Step 3. -- **Affirmative with conditions** ("go, but first change X", "yes but can we also...") → treat as discussion. Address the conditions, revise the approach if needed, then re-ask. -- **Questions or pushback** ("what about...", "I'm not sure about...", any adjustment) → discuss, revise approach, re-ask. -- **Abandonment** ("never mind", "not now", "stop") → stop. Nothing to clean up. +Proceed only on unconditional approval. If the user's response includes conditions, questions, or adjustments, treat it as discussion — address their input and re-ask. If the user abandons ("never mind", "stop"), stop — nothing to clean up. ### Step 3 — Create GitHub Issue @@ -171,12 +166,6 @@ Use the labels and milestone you already resolved in the Parsing section (before All five sections are required. Write for a non-developer audience — no code, no file paths. Acceptance Criteria must be concrete and verifiable (not vague goals). -**Complexity scale guidance (for agent use only — do not include the scale definition in the issue body):** -- **trivial** — single obvious check (e.g. color change, label text, toggle visibility) -- **moderate** — a few scenarios to verify, minor setup needed (e.g. form validation, a new UI component with a couple of states) -- **significant** — many scenarios, data setup, or cross-feature impact (e.g. multi-step workflow, permission changes across roles) -- **extensive** — complex data flows, integration testing, or edge cases spanning multiple areas (e.g. data import/export mapping, API contract changes consumed by multiple clients) - **Title rules:** - ✅ `Fix 'Contact Us' footer link pointing to 404 instead of /contact-us` - ❌ `Fix broken link` @@ -256,15 +245,41 @@ Tell the user: Ask: **"Does this match your understanding? Type `go` to start coding, or share any questions/adjustments first."** -**Intent classification (not keyword matching):** +Proceed only on unconditional approval. If the user's response includes conditions, questions, or adjustments, treat it as discussion — address their input and re-ask. If the user wants a fresh start, restart as Case A. If the user abandons, stop — nothing to clean up. + +### Step 3 — Investigation findings (conditional) + +If the investigation in Steps 1–2 revealed anything that isn't already stated or implied by the issue body — a root cause correction, a related side-effect, a project-wide gotcha — present the findings. If the investigation simply confirmed the ticket, skip this step silently and proceed to Step 4. + +Create a temp directory for this invocation: + +```bash +mkdir -p /tmp/CodeCannon && mktemp -d /tmp/CodeCannon/XXXXXX +``` + +Present numbered findings: -- **Affirmative with no conditions** ("go", "yes", "continue", "looks right") → proceed to Step 3. -- **Affirmative with conditions** ("go, but first...", "yes but let's also...") → treat as discussion. Address the conditions, then re-ask. -- **Questions or discussion** ("what about...", "can we change...", any adjustment) → discuss, then re-ask. -- **Fresh start** ("open a new one", "start fresh", "new ticket") → restart as Case A with a new description. -- **Abandonment** ("never mind", "not now", "stop") → stop. Nothing to clean up. +> The investigation surfaced the following: +> +> 1. +> 2. +> +> **post** as a comment to the ticket, or **skip** to continue. -### Step 3 — Check out branch +- `post` → use your file-writing tool (not Bash) to create `/investigation_comment.md`: + ```markdown + ## Investigation Findings + + - + - + ``` + Then post it: + ```bash + gh issue comment --body-file /investigation_comment.md + ``` +- `skip` → proceed silently. + +### Step 4 — Check out branch Ensure the base branch is up-to-date before branching: @@ -286,13 +301,7 @@ Verify: git branch --show-current ``` -Post a resumption comment: - -```bash -gh issue comment --body "Resuming work. " -``` - -### Step 4 — Write the code +### Step 5 — Write the code Continue from where work left off. Do NOT commit. @@ -310,4 +319,4 @@ When done, say: **"The code is ready for review. Please run `make dev` and test - The issue is assigned to `@me` at creation. If you are creating a ticket on someone else's behalf, remove the assignee after creation with `gh issue edit --remove-assignee @me`. - Apply resolved labels and milestone to every new issue. Label resolution order: per-invocation flag → pool selection from `bug, documentation, enhancement, chore` → omit `--label` entirely. Never apply a label outside `bug, documentation, enhancement, chore`. - Milestone resolution order: per-invocation flag → auto-detected from GitHub open milestones. Never prompt for a milestone more than once per invocation. - + diff --git a/.claude/commands/submit-for-review.md b/.claude/commands/submit-for-review.md index 3301719..b9fabb0 100644 --- a/.claude/commands/submit-for-review.md +++ b/.claude/commands/submit-for-review.md @@ -274,11 +274,7 @@ Then post it (do NOT use `--body` or heredocs): gh issue comment --body-file /resolution_comment.md ``` -**Resolution writing rules:** -- Write for PMs and BAs, not developers. Describe the *outcome*, not the implementation. -- Reference the original problem from the issue body so the resolution reads as a direct answer to it. -- Keep it to 1-3 sentences. If one sentence covers it, don't pad. -- Use the unqualified `#N` form for the PR reference. +Use the unqualified `#N` form for the PR reference (not `owner/repo#N`). Report success based on mode: "PR merged. Issues stay open until testing confirms the fix. Run `make deploy-preview` when ready to deploy to preview." @@ -349,4 +345,4 @@ If a single `gh issue create` call fails, report the failure for that finding an - `/submit-for-review` merges only to `dev` — never directly to `main`. - If `make merge` fails for any reason, report it and stop — do not attempt workarounds. - The follow-up issue offer in Step 9 runs only after a successful merge and only when the review produced non-blocking findings. Never prompt the user for follow-ups when the review blocked the merge — those findings should be fixed, not ticketed. - + diff --git a/.cursor/rules/start.mdc b/.cursor/rules/start.mdc index 2519980..6323594 100644 --- a/.cursor/rules/start.mdc +++ b/.cursor/rules/start.mdc @@ -116,12 +116,7 @@ Stop. Wait for the user to respond. The friendly text question is required regardless of harness mode. If your harness is currently in a preview / plan / dry-run mode where you cannot passively stop and wait (and must instead invoke the harness's own approval mechanism), still include the text question in your response. The harness's approval UI mediates the wait, but it is not a substitute for the question itself. Users expect to see the consistent text language across all modes; do not silently swap it for the harness's UI. -**Intent classification (not keyword matching):** - -- **Affirmative with no conditions** ("go", "yes", "looks good", "let's do it") → continue to Step 3. -- **Affirmative with conditions** ("go, but first change X", "yes but can we also...") → treat as discussion. Address the conditions, revise the approach if needed, then re-ask. -- **Questions or pushback** ("what about...", "I'm not sure about...", any adjustment) → discuss, revise approach, re-ask. -- **Abandonment** ("never mind", "not now", "stop") → stop. Nothing to clean up. +Proceed only on unconditional approval. If the user's response includes conditions, questions, or adjustments, treat it as discussion — address their input and re-ask. If the user abandons ("never mind", "stop"), stop — nothing to clean up. ### Step 3 — Create GitHub Issue @@ -177,12 +172,6 @@ Use the labels and milestone you already resolved in the Parsing section (before All five sections are required. Write for a non-developer audience — no code, no file paths. Acceptance Criteria must be concrete and verifiable (not vague goals). -**Complexity scale guidance (for agent use only — do not include the scale definition in the issue body):** -- **trivial** — single obvious check (e.g. color change, label text, toggle visibility) -- **moderate** — a few scenarios to verify, minor setup needed (e.g. form validation, a new UI component with a couple of states) -- **significant** — many scenarios, data setup, or cross-feature impact (e.g. multi-step workflow, permission changes across roles) -- **extensive** — complex data flows, integration testing, or edge cases spanning multiple areas (e.g. data import/export mapping, API contract changes consumed by multiple clients) - **Title rules:** - ✅ `Fix 'Contact Us' footer link pointing to 404 instead of /contact-us` - ❌ `Fix broken link` @@ -262,15 +251,41 @@ Tell the user: Ask: **"Does this match your understanding? Type `go` to start coding, or share any questions/adjustments first."** -**Intent classification (not keyword matching):** +Proceed only on unconditional approval. If the user's response includes conditions, questions, or adjustments, treat it as discussion — address their input and re-ask. If the user wants a fresh start, restart as Case A. If the user abandons, stop — nothing to clean up. + +### Step 3 — Investigation findings (conditional) + +If the investigation in Steps 1–2 revealed anything that isn't already stated or implied by the issue body — a root cause correction, a related side-effect, a project-wide gotcha — present the findings. If the investigation simply confirmed the ticket, skip this step silently and proceed to Step 4. + +Create a temp directory for this invocation: + +```bash +mkdir -p /tmp/CodeCannon && mktemp -d /tmp/CodeCannon/XXXXXX +``` + +Present numbered findings: -- **Affirmative with no conditions** ("go", "yes", "continue", "looks right") → proceed to Step 3. -- **Affirmative with conditions** ("go, but first...", "yes but let's also...") → treat as discussion. Address the conditions, then re-ask. -- **Questions or discussion** ("what about...", "can we change...", any adjustment) → discuss, then re-ask. -- **Fresh start** ("open a new one", "start fresh", "new ticket") → restart as Case A with a new description. -- **Abandonment** ("never mind", "not now", "stop") → stop. Nothing to clean up. +> The investigation surfaced the following: +> +> 1. +> 2. +> +> **post** as a comment to the ticket, or **skip** to continue. -### Step 3 — Check out branch +- `post` → use your file-writing tool (not Bash) to create `/investigation_comment.md`: + ```markdown + ## Investigation Findings + + - + - + ``` + Then post it: + ```bash + gh issue comment --body-file /investigation_comment.md + ``` +- `skip` → proceed silently. + +### Step 4 — Check out branch Ensure the base branch is up-to-date before branching: @@ -292,13 +307,7 @@ Verify: git branch --show-current ``` -Post a resumption comment: - -```bash -gh issue comment --body "Resuming work. " -``` - -### Step 4 — Write the code +### Step 5 — Write the code Continue from where work left off. Do NOT commit. @@ -316,4 +325,4 @@ When done, say: **"The code is ready for review. Please run `make dev` and test - The issue is assigned to `@me` at creation. If you are creating a ticket on someone else's behalf, remove the assignee after creation with `gh issue edit --remove-assignee @me`. - Apply resolved labels and milestone to every new issue. Label resolution order: per-invocation flag → pool selection from `bug, documentation, enhancement, chore` → omit `--label` entirely. Never apply a label outside `bug, documentation, enhancement, chore`. - Milestone resolution order: per-invocation flag → auto-detected from GitHub open milestones. Never prompt for a milestone more than once per invocation. - + diff --git a/.cursor/rules/submit-for-review.mdc b/.cursor/rules/submit-for-review.mdc index 29a2dfe..edae937 100644 --- a/.cursor/rules/submit-for-review.mdc +++ b/.cursor/rules/submit-for-review.mdc @@ -280,11 +280,7 @@ Then post it (do NOT use `--body` or heredocs): gh issue comment --body-file /resolution_comment.md ``` -**Resolution writing rules:** -- Write for PMs and BAs, not developers. Describe the *outcome*, not the implementation. -- Reference the original problem from the issue body so the resolution reads as a direct answer to it. -- Keep it to 1-3 sentences. If one sentence covers it, don't pad. -- Use the unqualified `#N` form for the PR reference. +Use the unqualified `#N` form for the PR reference (not `owner/repo#N`). Report success based on mode: "PR merged. Issues stay open until testing confirms the fix. Run `make deploy-preview` when ready to deploy to preview." @@ -355,4 +351,4 @@ If a single `gh issue create` call fails, report the failure for that finding an - `/submit-for-review` merges only to `dev` — never directly to `main`. - If `make merge` fails for any reason, report it and stop — do not attempt workarounds. - The follow-up issue offer in Step 9 runs only after a successful merge and only when the review produced non-blocking findings. Never prompt the user for follow-ups when the review blocked the merge — those findings should be fixed, not ticketed. - + diff --git a/.gemini/skills/start/SKILL.md b/.gemini/skills/start/SKILL.md index 697501b..5447e44 100644 --- a/.gemini/skills/start/SKILL.md +++ b/.gemini/skills/start/SKILL.md @@ -115,12 +115,7 @@ Stop. Wait for the user to respond. The friendly text question is required regardless of harness mode. If your harness is currently in a preview / plan / dry-run mode where you cannot passively stop and wait (and must instead invoke the harness's own approval mechanism), still include the text question in your response. The harness's approval UI mediates the wait, but it is not a substitute for the question itself. Users expect to see the consistent text language across all modes; do not silently swap it for the harness's UI. -**Intent classification (not keyword matching):** - -- **Affirmative with no conditions** ("go", "yes", "looks good", "let's do it") → continue to Step 3. -- **Affirmative with conditions** ("go, but first change X", "yes but can we also...") → treat as discussion. Address the conditions, revise the approach if needed, then re-ask. -- **Questions or pushback** ("what about...", "I'm not sure about...", any adjustment) → discuss, revise approach, re-ask. -- **Abandonment** ("never mind", "not now", "stop") → stop. Nothing to clean up. +Proceed only on unconditional approval. If the user's response includes conditions, questions, or adjustments, treat it as discussion — address their input and re-ask. If the user abandons ("never mind", "stop"), stop — nothing to clean up. ### Step 3 — Create GitHub Issue @@ -176,12 +171,6 @@ Use the labels and milestone you already resolved in the Parsing section (before All five sections are required. Write for a non-developer audience — no code, no file paths. Acceptance Criteria must be concrete and verifiable (not vague goals). -**Complexity scale guidance (for agent use only — do not include the scale definition in the issue body):** -- **trivial** — single obvious check (e.g. color change, label text, toggle visibility) -- **moderate** — a few scenarios to verify, minor setup needed (e.g. form validation, a new UI component with a couple of states) -- **significant** — many scenarios, data setup, or cross-feature impact (e.g. multi-step workflow, permission changes across roles) -- **extensive** — complex data flows, integration testing, or edge cases spanning multiple areas (e.g. data import/export mapping, API contract changes consumed by multiple clients) - **Title rules:** - ✅ `Fix 'Contact Us' footer link pointing to 404 instead of /contact-us` - ❌ `Fix broken link` @@ -261,15 +250,41 @@ Tell the user: Ask: **"Does this match your understanding? Type `go` to start coding, or share any questions/adjustments first."** -**Intent classification (not keyword matching):** +Proceed only on unconditional approval. If the user's response includes conditions, questions, or adjustments, treat it as discussion — address their input and re-ask. If the user wants a fresh start, restart as Case A. If the user abandons, stop — nothing to clean up. + +### Step 3 — Investigation findings (conditional) + +If the investigation in Steps 1–2 revealed anything that isn't already stated or implied by the issue body — a root cause correction, a related side-effect, a project-wide gotcha — present the findings. If the investigation simply confirmed the ticket, skip this step silently and proceed to Step 4. + +Create a temp directory for this invocation: + +```bash +mkdir -p /tmp/CodeCannon && mktemp -d /tmp/CodeCannon/XXXXXX +``` + +Present numbered findings: -- **Affirmative with no conditions** ("go", "yes", "continue", "looks right") → proceed to Step 3. -- **Affirmative with conditions** ("go, but first...", "yes but let's also...") → treat as discussion. Address the conditions, then re-ask. -- **Questions or discussion** ("what about...", "can we change...", any adjustment) → discuss, then re-ask. -- **Fresh start** ("open a new one", "start fresh", "new ticket") → restart as Case A with a new description. -- **Abandonment** ("never mind", "not now", "stop") → stop. Nothing to clean up. +> The investigation surfaced the following: +> +> 1. +> 2. +> +> **post** as a comment to the ticket, or **skip** to continue. -### Step 3 — Check out branch +- `post` → use your file-writing tool (not Bash) to create `/investigation_comment.md`: + ```markdown + ## Investigation Findings + + - + - + ``` + Then post it: + ```bash + gh issue comment --body-file /investigation_comment.md + ``` +- `skip` → proceed silently. + +### Step 4 — Check out branch Ensure the base branch is up-to-date before branching: @@ -291,13 +306,7 @@ Verify: git branch --show-current ``` -Post a resumption comment: - -```bash -gh issue comment --body "Resuming work. " -``` - -### Step 4 — Write the code +### Step 5 — Write the code Continue from where work left off. Do NOT commit. @@ -315,4 +324,4 @@ When done, say: **"The code is ready for review. Please run `make dev` and test - The issue is assigned to `@me` at creation. If you are creating a ticket on someone else's behalf, remove the assignee after creation with `gh issue edit --remove-assignee @me`. - Apply resolved labels and milestone to every new issue. Label resolution order: per-invocation flag → pool selection from `bug, documentation, enhancement, chore` → omit `--label` entirely. Never apply a label outside `bug, documentation, enhancement, chore`. - Milestone resolution order: per-invocation flag → auto-detected from GitHub open milestones. Never prompt for a milestone more than once per invocation. - + diff --git a/.gemini/skills/submit-for-review/SKILL.md b/.gemini/skills/submit-for-review/SKILL.md index d2dfef2..e4bc76f 100644 --- a/.gemini/skills/submit-for-review/SKILL.md +++ b/.gemini/skills/submit-for-review/SKILL.md @@ -279,11 +279,7 @@ Then post it (do NOT use `--body` or heredocs): gh issue comment --body-file /resolution_comment.md ``` -**Resolution writing rules:** -- Write for PMs and BAs, not developers. Describe the *outcome*, not the implementation. -- Reference the original problem from the issue body so the resolution reads as a direct answer to it. -- Keep it to 1-3 sentences. If one sentence covers it, don't pad. -- Use the unqualified `#N` form for the PR reference. +Use the unqualified `#N` form for the PR reference (not `owner/repo#N`). Report success based on mode: "PR merged. Issues stay open until testing confirms the fix. Run `make deploy-preview` when ready to deploy to preview." @@ -354,4 +350,4 @@ If a single `gh issue create` call fails, report the failure for that finding an - `/submit-for-review` merges only to `dev` — never directly to `main`. - If `make merge` fails for any reason, report it and stop — do not attempt workarounds. - The follow-up issue offer in Step 9 runs only after a successful merge and only when the review produced non-blocking findings. Never prompt the user for follow-ups when the review blocked the merge — those findings should be fixed, not ticketed. - + diff --git a/skills/start.md b/skills/start.md index 98a1bc8..9ea21fd 100644 --- a/skills/start.md +++ b/skills/start.md @@ -158,12 +158,7 @@ Stop. Wait for the user to respond. The friendly text question is required regardless of harness mode. If your harness is currently in a preview / plan / dry-run mode where you cannot passively stop and wait (and must instead invoke the harness's own approval mechanism), still include the text question in your response. The harness's approval UI mediates the wait, but it is not a substitute for the question itself. Users expect to see the consistent text language across all modes; do not silently swap it for the harness's UI. -**Intent classification (not keyword matching):** - -- **Affirmative with no conditions** ("go", "yes", "looks good", "let's do it") → continue to Step 3. -- **Affirmative with conditions** ("go, but first change X", "yes but can we also...") → treat as discussion. Address the conditions, revise the approach if needed, then re-ask. -- **Questions or pushback** ("what about...", "I'm not sure about...", any adjustment) → discuss, revise approach, re-ask. -- **Abandonment** ("never mind", "not now", "stop") → stop. Nothing to clean up. +Proceed only on unconditional approval. If the user's response includes conditions, questions, or adjustments, treat it as discussion — address their input and re-ask. If the user abandons ("never mind", "stop"), stop — nothing to clean up. ### Step 3 — Create GitHub Issue @@ -219,12 +214,6 @@ Use the labels and milestone you already resolved in the Parsing section (before All five sections are required. Write for a non-developer audience — no code, no file paths. Acceptance Criteria must be concrete and verifiable (not vague goals). -**Complexity scale guidance (for agent use only — do not include the scale definition in the issue body):** -- **trivial** — single obvious check (e.g. color change, label text, toggle visibility) -- **moderate** — a few scenarios to verify, minor setup needed (e.g. form validation, a new UI component with a couple of states) -- **significant** — many scenarios, data setup, or cross-feature impact (e.g. multi-step workflow, permission changes across roles) -- **extensive** — complex data flows, integration testing, or edge cases spanning multiple areas (e.g. data import/export mapping, API contract changes consumed by multiple clients) - **Title rules:** - ✅ `Fix 'Contact Us' footer link pointing to 404 instead of /contact-us` - ❌ `Fix broken link` @@ -320,15 +309,41 @@ Tell the user: Ask: **"Does this match your understanding? Type `go` to start coding, or share any questions/adjustments first."** -**Intent classification (not keyword matching):** +Proceed only on unconditional approval. If the user's response includes conditions, questions, or adjustments, treat it as discussion — address their input and re-ask. If the user wants a fresh start, restart as Case A. If the user abandons, stop — nothing to clean up. + +### Step 3 — Investigation findings (conditional) + +If the investigation in Steps 1–2 revealed anything that isn't already stated or implied by the issue body — a root cause correction, a related side-effect, a project-wide gotcha — present the findings. If the investigation simply confirmed the ticket, skip this step silently and proceed to Step 4. + +Create a temp directory for this invocation: + +```bash +mkdir -p /tmp/CodeCannon && mktemp -d /tmp/CodeCannon/XXXXXX +``` + +Present numbered findings: -- **Affirmative with no conditions** ("go", "yes", "continue", "looks right") → proceed to Step 3. -- **Affirmative with conditions** ("go, but first...", "yes but let's also...") → treat as discussion. Address the conditions, then re-ask. -- **Questions or discussion** ("what about...", "can we change...", any adjustment) → discuss, then re-ask. -- **Fresh start** ("open a new one", "start fresh", "new ticket") → restart as Case A with a new description. -- **Abandonment** ("never mind", "not now", "stop") → stop. Nothing to clean up. +> The investigation surfaced the following: +> +> 1. +> 2. +> +> **post** as a comment to the ticket, or **skip** to continue. -### Step 3 — Check out branch +- `post` → use your file-writing tool (not Bash) to create `/investigation_comment.md`: + ```markdown + ## Investigation Findings + + - + - + ``` + Then post it: + ```bash + gh issue comment --body-file /investigation_comment.md + ``` +- `skip` → proceed silently. + +### Step 4 — Check out branch Ensure the base branch is up-to-date before branching: @@ -366,13 +381,7 @@ Verify: git branch --show-current ``` -Post a resumption comment: - -```bash -gh issue comment --body "Resuming work. " -``` - -### Step 4 — Write the code +### Step 5 — Write the code Continue from where work left off. Do NOT commit. diff --git a/skills/submit-for-review.md b/skills/submit-for-review.md index 7dd5d95..6da4edc 100644 --- a/skills/submit-for-review.md +++ b/skills/submit-for-review.md @@ -309,11 +309,7 @@ Then post it (do NOT use `--body` or heredocs): gh issue comment --body-file /resolution_comment.md ``` -**Resolution writing rules:** -- Write for PMs and BAs, not developers. Describe the *outcome*, not the implementation. -- Reference the original problem from the issue body so the resolution reads as a direct answer to it. -- Keep it to 1-3 sentences. If one sentence covers it, don't pad. -- Use the unqualified `#N` form for the PR reference. +Use the unqualified `#N` form for the PR reference (not `owner/repo#N`). Report success based on mode: {{#if !BRANCH_DEV}}