diff --git a/.agents/skills/gstack-plan-eng-review/SKILL.md b/.agents/skills/gstack-plan-eng-review/SKILL.md
index dcc82f9c..53fa5c28 100644
--- a/.agents/skills/gstack-plan-eng-review/SKILL.md
+++ b/.agents/skills/gstack-plan-eng-review/SKILL.md
@@ -338,11 +338,11 @@ ls -d test/ tests/ spec/ __tests__/ cypress/ e2e/ 2>/dev/null
3. **If no framework detected:** still produce the coverage diagram, but skip test generation.
-**Step 1. Trace every codepath changed** using `git diff origin/...HEAD`:
+**Step 1. Trace every codepath in the plan:**
-Read every changed file. For each one, trace how data flows through the code — don't just list functions, actually follow the execution:
+Read the plan document. For each new feature, service, endpoint, or component described, trace how data will flow through the code — don't just list planned functions, actually follow the planned execution:
-1. **Read the diff.** For each changed file, read the full file (not just the diff hunk) to understand context.
+1. **Read the plan.** For each planned component, understand what it does and how it connects to existing code.
2. **Trace data flow.** Starting from each entry point (route handler, exported function, event listener, component render), follow the data through every branch:
- Where does input come from? (request params, props, database, API call)
- What transforms it? (validation, mapping, computation)
diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md
index 6f350355..3c0b4d06 100644
--- a/plan-eng-review/SKILL.md
+++ b/plan-eng-review/SKILL.md
@@ -346,11 +346,11 @@ ls -d test/ tests/ spec/ __tests__/ cypress/ e2e/ 2>/dev/null
3. **If no framework detected:** still produce the coverage diagram, but skip test generation.
-**Step 1. Trace every codepath changed** using `git diff origin/...HEAD`:
+**Step 1. Trace every codepath in the plan:**
-Read every changed file. For each one, trace how data flows through the code — don't just list functions, actually follow the execution:
+Read the plan document. For each new feature, service, endpoint, or component described, trace how data will flow through the code — don't just list planned functions, actually follow the planned execution:
-1. **Read the diff.** For each changed file, read the full file (not just the diff hunk) to understand context.
+1. **Read the plan.** For each planned component, understand what it does and how it connects to existing code.
2. **Trace data flow.** Starting from each entry point (route handler, exported function, event listener, component render), follow the data through every branch:
- Where does input come from? (request params, props, database, API call)
- What transforms it? (validation, mapping, computation)
diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts
index f0b2b326..096dd4be 100644
--- a/scripts/gen-skill-docs.ts
+++ b/scripts/gen-skill-docs.ts
@@ -1313,13 +1313,23 @@ find . -name '*.test.*' -o -name '*.spec.*' -o -name '*_test.*' -o -name '*_spec
Store this number for the PR body.`);
}
- // ── Codepath tracing methodology (shared) ──
+ // ── Codepath tracing methodology (shared, with mode-specific source) ──
+ const traceSource = mode === 'plan'
+ ? `**Step 1. Trace every codepath in the plan:**
+
+Read the plan document. For each new feature, service, endpoint, or component described, trace how data will flow through the code — don't just list planned functions, actually follow the planned execution:`
+ : `**${mode === 'ship' ? '1' : 'Step 1'}. Trace every codepath changed** using \`git diff origin/...HEAD\`:
+
+Read every changed file. For each one, trace how data flows through the code — don't just list functions, actually follow the execution:`;
+
+ const traceStep1 = mode === 'plan'
+ ? `1. **Read the plan.** For each planned component, understand what it does and how it connects to existing code.`
+ : `1. **Read the diff.** For each changed file, read the full file (not just the diff hunk) to understand context.`;
+
sections.push(`
-**${mode === 'ship' ? '1' : 'Step 1'}. Trace every codepath changed** using \`git diff origin/...HEAD\`:
+${traceSource}
-Read every changed file. For each one, trace how data flows through the code — don't just list functions, actually follow the execution:
-
-1. **Read the diff.** For each changed file, read the full file (not just the diff hunk) to understand context.
+${traceStep1}
2. **Trace data flow.** Starting from each entry point (route handler, exported function, event listener, component render), follow the data through every branch:
- Where does input come from? (request params, props, database, API call)
- What transforms it? (validation, mapping, computation)
diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts
index a8dec0a2..7a1baf97 100644
--- a/test/gen-skill-docs.test.ts
+++ b/test/gen-skill-docs.test.ts
@@ -425,7 +425,6 @@ describe('TEST_COVERAGE_AUDIT placeholders', () => {
test('all three modes share codepath tracing methodology', () => {
const sharedPhrases = [
- 'Trace every codepath changed',
'Trace data flow',
'Diagram the execution',
'Quality scoring rubric',
@@ -438,6 +437,12 @@ describe('TEST_COVERAGE_AUDIT placeholders', () => {
expect(shipSkill).toContain(phrase);
expect(reviewSkill).toContain(phrase);
}
+ // Plan mode traces the plan, not a git diff
+ expect(planSkill).toContain('Trace every codepath in the plan');
+ expect(planSkill).not.toContain('git diff origin');
+ // Ship and review modes trace the diff
+ expect(shipSkill).toContain('Trace every codepath changed');
+ expect(reviewSkill).toContain('Trace every codepath changed');
});
test('all three modes include E2E decision matrix', () => {