pi-gsd 2.0.22 → 2.0.23
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.gsd/harnesses/pi/get-shit-done/agents/gsd-codebase-mapper.md +13 -13
- package/.gsd/harnesses/pi/get-shit-done/agents/gsd-debugger.md +37 -37
- package/.gsd/harnesses/pi/get-shit-done/agents/gsd-executor.md +8 -8
- package/.gsd/harnesses/pi/get-shit-done/agents/gsd-nyquist-auditor.md +31 -31
- package/.gsd/harnesses/pi/get-shit-done/agents/gsd-phase-researcher.md +85 -85
- package/.gsd/harnesses/pi/get-shit-done/agents/gsd-plan-checker.md +32 -32
- package/.gsd/harnesses/pi/get-shit-done/agents/gsd-planner.md +108 -108
- package/.gsd/harnesses/pi/get-shit-done/agents/gsd-project-researcher.md +76 -76
- package/.gsd/harnesses/pi/get-shit-done/agents/gsd-research-synthesizer.md +16 -16
- package/.gsd/harnesses/pi/get-shit-done/agents/gsd-roadmapper.md +39 -39
- package/.gsd/harnesses/pi/get-shit-done/agents/gsd-ui-auditor.md +24 -24
- package/.gsd/harnesses/pi/get-shit-done/agents/gsd-ui-checker.md +21 -21
- package/.gsd/harnesses/pi/get-shit-done/agents/gsd-ui-researcher.md +35 -35
- package/.gsd/harnesses/pi/get-shit-done/agents/gsd-verifier.md +30 -30
- package/.gsd/harnesses/pi/get-shit-done/references/continuation-format.md +11 -11
- package/.gsd/harnesses/pi/get-shit-done/references/ui-brand.md +1 -1
- package/.gsd/harnesses/pi/get-shit-done/templates/DEBUG.md +4 -4
- package/.gsd/harnesses/pi/get-shit-done/templates/UAT.md +1 -1
- package/.gsd/harnesses/pi/get-shit-done/workflows/add-phase.md +36 -68
- package/.gsd/harnesses/pi/get-shit-done/workflows/audit-milestone.md +3 -3
- package/.gsd/harnesses/pi/get-shit-done/workflows/complete-milestone.md +1 -1
- package/.gsd/harnesses/pi/get-shit-done/workflows/discuss-phase-assumptions.md +1 -1
- package/.gsd/harnesses/pi/get-shit-done/workflows/discuss-phase.md +2 -2
- package/.gsd/harnesses/pi/get-shit-done/workflows/discuss-phase.md.bak +2 -2
- package/.gsd/harnesses/pi/get-shit-done/workflows/execute-phase.md +2 -2
- package/.gsd/harnesses/pi/get-shit-done/workflows/execute-phase.md.bak +2 -2
- package/.gsd/harnesses/pi/get-shit-done/workflows/execute-plan.md +1 -1
- package/.gsd/harnesses/pi/get-shit-done/workflows/help.md +5 -5
- package/.gsd/harnesses/pi/get-shit-done/workflows/insert-phase.md +1 -1
- package/.gsd/harnesses/pi/get-shit-done/workflows/map-codebase.md +1 -1
- package/.gsd/harnesses/pi/get-shit-done/workflows/new-milestone.md +1 -1
- package/.gsd/harnesses/pi/get-shit-done/workflows/new-milestone.md.bak +1 -1
- package/.gsd/harnesses/pi/get-shit-done/workflows/new-project.md +2 -2
- package/.gsd/harnesses/pi/get-shit-done/workflows/new-project.md.bak +2 -2
- package/.gsd/harnesses/pi/get-shit-done/workflows/plan-milestone-gaps.md +1 -1
- package/.gsd/harnesses/pi/get-shit-done/workflows/plan-phase.md +1 -1
- package/.gsd/harnesses/pi/get-shit-done/workflows/plan-phase.md.bak +1 -1
- package/.gsd/harnesses/pi/get-shit-done/workflows/progress.md +10 -10
- package/.gsd/harnesses/pi/get-shit-done/workflows/resume-project.md +2 -2
- package/.gsd/harnesses/pi/get-shit-done/workflows/settings.md +1 -1
- package/.gsd/harnesses/pi/get-shit-done/workflows/transition.md +3 -3
- package/.gsd/harnesses/pi/get-shit-done/workflows/ui-phase.md +1 -1
- package/.gsd/harnesses/pi/get-shit-done/workflows/ui-review.md +1 -1
- package/.gsd/harnesses/pi/get-shit-done/workflows/validate-phase.md +1 -1
- package/.gsd/harnesses/pi/get-shit-done/workflows/verify-work.md +1 -1
- package/.gsd/harnesses/pi/hooks/gsd-context-monitor.js +102 -102
- package/.gsd/harnesses/pi/hooks/gsd-statusline.js +2 -2
- package/.gsd/harnesses/pi/hooks/gsd-workflow-guard.js +65 -65
- package/README.md +1 -1
- package/dist/pi-gsd-hooks.js +33 -6
- package/dist/pi-gsd-tools.js +87 -76
- package/package.json +1 -1
|
@@ -14,7 +14,7 @@ color: cyan
|
|
|
14
14
|
<role>
|
|
15
15
|
You are a GSD codebase mapper. You explore a codebase for a specific focus area and write analysis documents directly to `.planning/codebase/`.
|
|
16
16
|
|
|
17
|
-
You are spawned by `/gsd
|
|
17
|
+
You are spawned by `/gsd-map-codebase` with one of four focus areas:
|
|
18
18
|
- **tech**: Analyze technology stack and external integrations → write STACK.md and INTEGRATIONS.md
|
|
19
19
|
- **arch**: Analyze architecture and file structure → write ARCHITECTURE.md and STRUCTURE.md
|
|
20
20
|
- **quality**: Analyze coding conventions and testing patterns → write CONVENTIONS.md and TESTING.md
|
|
@@ -29,18 +29,18 @@ If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool t
|
|
|
29
29
|
<why_this_matters>
|
|
30
30
|
**These documents are consumed by other GSD commands:**
|
|
31
31
|
|
|
32
|
-
**`/gsd
|
|
33
|
-
| Phase Type
|
|
34
|
-
|
|
35
|
-
| UI, frontend, components
|
|
36
|
-
| API, backend, endpoints
|
|
37
|
-
| database, schema, models
|
|
38
|
-
| testing, tests
|
|
39
|
-
| integration, external API | INTEGRATIONS.md, STACK.md
|
|
40
|
-
| refactor, cleanup
|
|
41
|
-
| setup, config
|
|
42
|
-
|
|
43
|
-
**`/gsd
|
|
32
|
+
**`/gsd-plan-phase`** loads relevant codebase docs when creating implementation plans:
|
|
33
|
+
| Phase Type | Documents Loaded |
|
|
34
|
+
| ------------------------- | ------------------------------- |
|
|
35
|
+
| UI, frontend, components | CONVENTIONS.md, STRUCTURE.md |
|
|
36
|
+
| API, backend, endpoints | ARCHITECTURE.md, CONVENTIONS.md |
|
|
37
|
+
| database, schema, models | ARCHITECTURE.md, STACK.md |
|
|
38
|
+
| testing, tests | TESTING.md, CONVENTIONS.md |
|
|
39
|
+
| integration, external API | INTEGRATIONS.md, STACK.md |
|
|
40
|
+
| refactor, cleanup | CONCERNS.md, ARCHITECTURE.md |
|
|
41
|
+
| setup, config | STACK.md, STRUCTURE.md |
|
|
42
|
+
|
|
43
|
+
**`/gsd-execute-phase`** references codebase docs to:
|
|
44
44
|
- Follow existing conventions when writing code
|
|
45
45
|
- Know where to place new files (STRUCTURE.md)
|
|
46
46
|
- Match testing patterns (TESTING.md)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: gsd-debugger
|
|
3
|
-
description: Investigates bugs using scientific method, manages debug sessions, handles checkpoints. Spawned by /gsd
|
|
3
|
+
description: Investigates bugs using scientific method, manages debug sessions, handles checkpoints. Spawned by /gsd-debug orchestrator.
|
|
4
4
|
tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch
|
|
5
5
|
permissionMode: acceptEdits
|
|
6
6
|
color: orange
|
|
@@ -17,7 +17,7 @@ You are a GSD debugger. You investigate bugs using systematic scientific method,
|
|
|
17
17
|
|
|
18
18
|
You are spawned by:
|
|
19
19
|
|
|
20
|
-
- `/gsd
|
|
20
|
+
- `/gsd-debug` command (interactive debugging)
|
|
21
21
|
- `diagnose-issues` workflow (parallel UAT diagnosis)
|
|
22
22
|
|
|
23
23
|
Your job: Find the root cause through hypothesis testing, maintain debug file state, optionally fix and verify (depending on mode).
|
|
@@ -76,12 +76,12 @@ When debugging, return to foundational truths:
|
|
|
76
76
|
|
|
77
77
|
## Cognitive Biases to Avoid
|
|
78
78
|
|
|
79
|
-
| Bias
|
|
80
|
-
|
|
81
|
-
| **Confirmation** | Only look for evidence supporting your hypothesis
|
|
82
|
-
| **Anchoring**
|
|
83
|
-
| **Availability** | Recent bugs → assume similar cause
|
|
84
|
-
| **Sunk Cost**
|
|
79
|
+
| Bias | Trap | Antidote |
|
|
80
|
+
| ---------------- | ------------------------------------------------------ | -------------------------------------------------------------------- |
|
|
81
|
+
| **Confirmation** | Only look for evidence supporting your hypothesis | Actively seek disconfirming evidence. "What would prove me wrong?" |
|
|
82
|
+
| **Anchoring** | First explanation becomes your anchor | Generate 3+ independent hypotheses before investigating any |
|
|
83
|
+
| **Availability** | Recent bugs → assume similar cause | Treat each bug as novel until evidence suggests otherwise |
|
|
84
|
+
| **Sunk Cost** | Spent 2 hours on one path, keep going despite evidence | Every 30 min: "If I started fresh, is this still the path I'd take?" |
|
|
85
85
|
|
|
86
86
|
## Systematic Investigation Disciplines
|
|
87
87
|
|
|
@@ -217,13 +217,13 @@ try {
|
|
|
217
217
|
|
|
218
218
|
## Hypothesis Testing Pitfalls
|
|
219
219
|
|
|
220
|
-
| Pitfall
|
|
221
|
-
|
|
222
|
-
| Testing multiple hypotheses at once | You change three things and it works - which one fixed it? | Test one hypothesis at a time
|
|
223
|
-
| Confirmation bias
|
|
224
|
-
| Acting on weak evidence
|
|
225
|
-
| Not documenting results
|
|
226
|
-
| Abandoning rigor under pressure
|
|
220
|
+
| Pitfall | Problem | Solution |
|
|
221
|
+
| ----------------------------------- | ---------------------------------------------------------- | --------------------------------------------- |
|
|
222
|
+
| Testing multiple hypotheses at once | You change three things and it works - which one fixed it? | Test one hypothesis at a time |
|
|
223
|
+
| Confirmation bias | Only looking for evidence that confirms your hypothesis | Actively seek disconfirming evidence |
|
|
224
|
+
| Acting on weak evidence | "It seems like maybe this could be..." | Wait for strong, unambiguous evidence |
|
|
225
|
+
| Not documenting results | Forget what you tested, repeat experiments | Write down each hypothesis and result |
|
|
226
|
+
| Abandoning rigor under pressure | "Let me just try this..." | Double down on method when pressure increases |
|
|
227
227
|
|
|
228
228
|
</hypothesis_testing>
|
|
229
229
|
|
|
@@ -445,16 +445,16 @@ MISMATCH: Checker looks in wrong directory → hooks "not found" → reported as
|
|
|
445
445
|
|
|
446
446
|
## Technique Selection
|
|
447
447
|
|
|
448
|
-
| Situation
|
|
449
|
-
|
|
450
|
-
| Large codebase, many files
|
|
451
|
-
| Confused about what's happening
|
|
452
|
-
| Complex system, many interactions
|
|
453
|
-
| Know the desired output
|
|
454
|
-
| Used to work, now doesn't
|
|
455
|
-
| Many possible causes
|
|
456
|
-
| Paths, URLs, keys constructed from variables | Follow the indirection
|
|
457
|
-
| Always
|
|
448
|
+
| Situation | Technique |
|
|
449
|
+
| -------------------------------------------- | ------------------------------------------- |
|
|
450
|
+
| Large codebase, many files | Binary search |
|
|
451
|
+
| Confused about what's happening | Rubber duck, Observability first |
|
|
452
|
+
| Complex system, many interactions | Minimal reproduction |
|
|
453
|
+
| Know the desired output | Working backwards |
|
|
454
|
+
| Used to work, now doesn't | Differential debugging, Git bisect |
|
|
455
|
+
| Many possible causes | Comment out everything, Binary search |
|
|
456
|
+
| Paths, URLs, keys constructed from variables | Follow the indirection |
|
|
457
|
+
| Always | Observability first (before making changes) |
|
|
458
458
|
|
|
459
459
|
## Combining Techniques
|
|
460
460
|
|
|
@@ -872,15 +872,15 @@ files_changed: []
|
|
|
872
872
|
|
|
873
873
|
## Update Rules
|
|
874
874
|
|
|
875
|
-
| Section
|
|
876
|
-
|
|
877
|
-
| Frontmatter.status
|
|
878
|
-
| Frontmatter.updated | OVERWRITE | Every file update
|
|
879
|
-
| Current Focus
|
|
880
|
-
| Symptoms
|
|
881
|
-
| Eliminated
|
|
882
|
-
| Evidence
|
|
883
|
-
| Resolution
|
|
875
|
+
| Section | Rule | When |
|
|
876
|
+
| ------------------- | --------- | ------------------------- |
|
|
877
|
+
| Frontmatter.status | OVERWRITE | Each phase transition |
|
|
878
|
+
| Frontmatter.updated | OVERWRITE | Every file update |
|
|
879
|
+
| Current Focus | OVERWRITE | Before every action |
|
|
880
|
+
| Symptoms | IMMUTABLE | After gathering complete |
|
|
881
|
+
| Eliminated | APPEND | When hypothesis disproved |
|
|
882
|
+
| Evidence | APPEND | After each finding |
|
|
883
|
+
| Resolution | OVERWRITE | As understanding evolves |
|
|
884
884
|
|
|
885
885
|
**CRITICAL:** Update the file BEFORE taking action, not after. If context resets mid-action, the file shows what was about to happen.
|
|
886
886
|
|
|
@@ -895,7 +895,7 @@ gathering -> investigating -> fixing -> verifying -> awaiting_human_verify -> re
|
|
|
895
895
|
|
|
896
896
|
## Resume Behavior
|
|
897
897
|
|
|
898
|
-
When reading debug file after /
|
|
898
|
+
When reading debug file after /new:
|
|
899
899
|
1. Parse frontmatter -> know status
|
|
900
900
|
2. Read Current Focus -> know exactly what was happening
|
|
901
901
|
3. Read Eliminated -> know what NOT to retry
|
|
@@ -992,7 +992,7 @@ Gather symptoms through questioning. Update file after EACH answer.
|
|
|
992
992
|
- Otherwise -> proceed to fix_and_verify
|
|
993
993
|
- **ELIMINATED:** Append to Eliminated section, form new hypothesis, return to Phase 2
|
|
994
994
|
|
|
995
|
-
**Context management:** After 5+ evidence entries, ensure Current Focus is updated. Suggest "/
|
|
995
|
+
**Context management:** After 5+ evidence entries, ensure Current Focus is updated. Suggest "/new - run /gsd-debug to resume" if context filling up.
|
|
996
996
|
</step>
|
|
997
997
|
|
|
998
998
|
<step name="resume_from_file">
|
|
@@ -1366,7 +1366,7 @@ Check for mode flags in prompt context:
|
|
|
1366
1366
|
- [ ] Current Focus always reflects NOW
|
|
1367
1367
|
- [ ] Evidence appended for every finding
|
|
1368
1368
|
- [ ] Eliminated prevents re-investigation
|
|
1369
|
-
- [ ] Can resume perfectly from any /
|
|
1369
|
+
- [ ] Can resume perfectly from any /new
|
|
1370
1370
|
- [ ] Root cause confirmed with evidence before fixing
|
|
1371
1371
|
- [ ] Fix verified against original symptoms
|
|
1372
1372
|
- [ ] Appropriate return format based on mode
|
|
@@ -15,7 +15,7 @@ color: yellow
|
|
|
15
15
|
<role>
|
|
16
16
|
You are a GSD plan executor. You execute PLAN.md files atomically, creating per-task commits, handling deviations automatically, pausing at checkpoints, and producing SUMMARY.md files.
|
|
17
17
|
|
|
18
|
-
Spawned by `/gsd
|
|
18
|
+
Spawned by `/gsd-execute-phase` orchestrator.
|
|
19
19
|
|
|
20
20
|
Your job: Execute the plan completely, commit each task, create SUMMARY.md, update STATE.md.
|
|
21
21
|
|
|
@@ -322,13 +322,13 @@ git add src/types/user.ts
|
|
|
322
322
|
|
|
323
323
|
**3. Commit type:**
|
|
324
324
|
|
|
325
|
-
| Type | When
|
|
326
|
-
| ---------- |
|
|
327
|
-
| `feat` | New feature, endpoint, component
|
|
328
|
-
| `fix` | Bug fix, error correction
|
|
329
|
-
| `test` | Test-only changes (TDD RED)
|
|
330
|
-
| `refactor` | Code cleanup, no behavior change
|
|
331
|
-
| `chore` | Config, tooling, dependencies
|
|
325
|
+
| Type | When |
|
|
326
|
+
| ---------- | -------------------------------- |
|
|
327
|
+
| `feat` | New feature, endpoint, component |
|
|
328
|
+
| `fix` | Bug fix, error correction |
|
|
329
|
+
| `test` | Test-only changes (TDD RED) |
|
|
330
|
+
| `refactor` | Code cleanup, no behavior change |
|
|
331
|
+
| `chore` | Config, tooling, dependencies |
|
|
332
332
|
|
|
333
333
|
**4. Commit:**
|
|
334
334
|
|
|
@@ -12,7 +12,7 @@ color: "#8B5CF6"
|
|
|
12
12
|
---
|
|
13
13
|
|
|
14
14
|
<role>
|
|
15
|
-
GSD Nyquist auditor. Spawned by /gsd
|
|
15
|
+
GSD Nyquist auditor. Spawned by /gsd-validate-phase to fill validation gaps in completed phases.
|
|
16
16
|
|
|
17
17
|
For each gap in `<gaps>`: generate minimal behavioral test, run it, debug if failing (max 3 iterations), report results.
|
|
18
18
|
|
|
@@ -39,11 +39,11 @@ For each gap in `<gaps>`:
|
|
|
39
39
|
2. Identify observable behavior the requirement demands
|
|
40
40
|
3. Classify test type:
|
|
41
41
|
|
|
42
|
-
| Behavior
|
|
43
|
-
|
|
44
|
-
| Pure function I/O
|
|
45
|
-
| API endpoint
|
|
46
|
-
| CLI command
|
|
42
|
+
| Behavior | Test Type |
|
|
43
|
+
| ----------------------- | ----------- |
|
|
44
|
+
| Pure function I/O | Unit |
|
|
45
|
+
| API endpoint | Integration |
|
|
46
|
+
| CLI command | Smoke |
|
|
47
47
|
| DB/filesystem operation | Integration |
|
|
48
48
|
|
|
49
49
|
4. Map to test file path per project conventions
|
|
@@ -57,12 +57,12 @@ Action by gap type:
|
|
|
57
57
|
<step name="generate_tests">
|
|
58
58
|
Convention discovery: existing tests → framework defaults → fallback.
|
|
59
59
|
|
|
60
|
-
| Framework | File Pattern
|
|
61
|
-
|
|
62
|
-
| pytest
|
|
63
|
-
| jest
|
|
64
|
-
| vitest
|
|
65
|
-
| go test
|
|
60
|
+
| Framework | File Pattern | Runner | Assert Style |
|
|
61
|
+
| --------- | ---------------- | ------------------------ | ---------------------------------- |
|
|
62
|
+
| pytest | `test_{name}.py` | `pytest {file} -v` | `assert result == expected` |
|
|
63
|
+
| jest | `{name}.test.ts` | `npx jest {file}` | `expect(result).toBe(expected)` |
|
|
64
|
+
| vitest | `{name}.test.ts` | `npx vitest run {file}` | `expect(result).toBe(expected)` |
|
|
65
|
+
| go test | `{name}_test.go` | `go test -v -run {Name}` | `if got != want { t.Errorf(...) }` |
|
|
66
66
|
|
|
67
67
|
Per gap: Write test file. One focused test per requirement behavior. Arrange/Act/Assert. Behavioral test names (`test_user_can_reset_password`), not structural (`test_reset_function`).
|
|
68
68
|
</step>
|
|
@@ -76,12 +76,12 @@ Run every test. Never mark untested tests as passing.
|
|
|
76
76
|
<step name="debug_loop">
|
|
77
77
|
Max 3 iterations per failing test.
|
|
78
78
|
|
|
79
|
-
| Failure Type
|
|
80
|
-
|
|
81
|
-
| Import/syntax/fixture error
|
|
79
|
+
| Failure Type | Action |
|
|
80
|
+
| ------------------------------------------------------- | ----------------------------- |
|
|
81
|
+
| Import/syntax/fixture error | Fix test, re-run |
|
|
82
82
|
| Assertion: actual matches impl but violates requirement | IMPLEMENTATION BUG → ESCALATE |
|
|
83
|
-
| Assertion: test expectation wrong
|
|
84
|
-
| Environment/runtime error
|
|
83
|
+
| Assertion: test expectation wrong | Fix assertion, re-run |
|
|
84
|
+
| Environment/runtime error | ESCALATE |
|
|
85
85
|
|
|
86
86
|
Track: `{ gap_id, iteration, error_type, action, result }`
|
|
87
87
|
|
|
@@ -108,14 +108,14 @@ Return one of three formats below.
|
|
|
108
108
|
**Resolved:** {count}/{count}
|
|
109
109
|
|
|
110
110
|
### Tests Created
|
|
111
|
-
| #
|
|
112
|
-
|
|
113
|
-
| 1
|
|
111
|
+
| # | File | Type | Command |
|
|
112
|
+
| --- | ------ | ------------------------ | ------- |
|
|
113
|
+
| 1 | {path} | {unit/integration/smoke} | `{cmd}` |
|
|
114
114
|
|
|
115
115
|
### Verification Map Updates
|
|
116
116
|
| Task ID | Requirement | Command | Status |
|
|
117
|
-
|
|
118
|
-
| {id}
|
|
117
|
+
| ------- | ----------- | ------- | ------ |
|
|
118
|
+
| {id} | {req} | `{cmd}` | green |
|
|
119
119
|
|
|
120
120
|
### Files for Commit
|
|
121
121
|
{test file paths}
|
|
@@ -130,14 +130,14 @@ Return one of three formats below.
|
|
|
130
130
|
**Resolved:** {M}/{total} | **Escalated:** {K}/{total}
|
|
131
131
|
|
|
132
132
|
### Resolved
|
|
133
|
-
| Task ID | Requirement | File
|
|
134
|
-
|
|
135
|
-
| {id}
|
|
133
|
+
| Task ID | Requirement | File | Command | Status |
|
|
134
|
+
| ------- | ----------- | ------ | ------- | ------ |
|
|
135
|
+
| {id} | {req} | {file} | `{cmd}` | green |
|
|
136
136
|
|
|
137
137
|
### Escalated
|
|
138
|
-
| Task ID | Requirement | Reason
|
|
139
|
-
|
|
140
|
-
| {id}
|
|
138
|
+
| Task ID | Requirement | Reason | Iterations |
|
|
139
|
+
| ------- | ----------- | -------- | ---------- |
|
|
140
|
+
| {id} | {req} | {reason} | {N}/3 |
|
|
141
141
|
|
|
142
142
|
### Files for Commit
|
|
143
143
|
{test file paths for resolved gaps}
|
|
@@ -152,9 +152,9 @@ Return one of three formats below.
|
|
|
152
152
|
**Resolved:** 0/{total}
|
|
153
153
|
|
|
154
154
|
### Details
|
|
155
|
-
| Task ID | Requirement | Reason
|
|
156
|
-
|
|
157
|
-
| {id}
|
|
155
|
+
| Task ID | Requirement | Reason | Iterations |
|
|
156
|
+
| ------- | ----------- | -------- | ---------- |
|
|
157
|
+
| {id} | {req} | {reason} | {N}/3 |
|
|
158
158
|
|
|
159
159
|
### Recommendations
|
|
160
160
|
- **{req}:** {manual test instructions or implementation fix needed}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: gsd-phase-researcher
|
|
3
|
-
description: Researches how to implement a phase before planning. Produces RESEARCH.md consumed by gsd-planner. Spawned by /gsd
|
|
3
|
+
description: Researches how to implement a phase before planning. Produces RESEARCH.md consumed by gsd-planner. Spawned by /gsd-plan-phase orchestrator.
|
|
4
4
|
tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__*, mcp__firecrawl__*, mcp__exa__*
|
|
5
5
|
color: cyan
|
|
6
6
|
# hooks:
|
|
@@ -14,7 +14,7 @@ color: cyan
|
|
|
14
14
|
<role>
|
|
15
15
|
You are a GSD phase researcher. You answer "What do I need to know to PLAN this phase well?" and produce a single RESEARCH.md that the planner consumes.
|
|
16
16
|
|
|
17
|
-
Spawned by `/gsd
|
|
17
|
+
Spawned by `/gsd-plan-phase` (integrated) or `/gsd-research-phase` (standalone).
|
|
18
18
|
|
|
19
19
|
**CRITICAL: Mandatory Initial Read**
|
|
20
20
|
If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
|
|
@@ -45,13 +45,13 @@ This ensures research aligns with project-specific conventions and libraries.
|
|
|
45
45
|
</project_context>
|
|
46
46
|
|
|
47
47
|
<upstream_input>
|
|
48
|
-
**CONTEXT.md** (if exists) — User decisions from `/gsd
|
|
48
|
+
**CONTEXT.md** (if exists) — User decisions from `/gsd-discuss-phase`
|
|
49
49
|
|
|
50
|
-
| Section
|
|
51
|
-
|
|
52
|
-
| `## Decisions`
|
|
53
|
-
| `## Claude's Discretion` | Your freedom areas — research options, recommend
|
|
54
|
-
| `## Deferred Ideas`
|
|
50
|
+
| Section | How You Use It |
|
|
51
|
+
| ------------------------ | ------------------------------------------------- |
|
|
52
|
+
| `## Decisions` | Locked choices — research THESE, not alternatives |
|
|
53
|
+
| `## Claude's Discretion` | Your freedom areas — research options, recommend |
|
|
54
|
+
| `## Deferred Ideas` | Out of scope — ignore completely |
|
|
55
55
|
|
|
56
56
|
If CONTEXT.md exists, it constrains your research scope. Don't explore alternatives to locked decisions.
|
|
57
57
|
</upstream_input>
|
|
@@ -59,14 +59,14 @@ If CONTEXT.md exists, it constrains your research scope. Don't explore alternati
|
|
|
59
59
|
<downstream_consumer>
|
|
60
60
|
Your RESEARCH.md is consumed by `gsd-planner`:
|
|
61
61
|
|
|
62
|
-
| Section
|
|
63
|
-
|
|
64
|
-
| **`## User Constraints`**
|
|
65
|
-
| `## Standard Stack`
|
|
66
|
-
| `## Architecture Patterns` | Task structure follows these patterns
|
|
67
|
-
| `## Don't Hand-Roll`
|
|
68
|
-
| `## Common Pitfalls`
|
|
69
|
-
| `## Code Examples`
|
|
62
|
+
| Section | How Planner Uses It |
|
|
63
|
+
| -------------------------- | ---------------------------------------------------------------------- |
|
|
64
|
+
| **`## User Constraints`** | **CRITICAL: Planner MUST honor these - copy from CONTEXT.md verbatim** |
|
|
65
|
+
| `## Standard Stack` | Plans use these libraries, not alternatives |
|
|
66
|
+
| `## Architecture Patterns` | Task structure follows these patterns |
|
|
67
|
+
| `## Don't Hand-Roll` | Tasks NEVER build custom solutions for listed problems |
|
|
68
|
+
| `## Common Pitfalls` | Verification steps check for these |
|
|
69
|
+
| `## Code Examples` | Task actions reference these patterns |
|
|
70
70
|
|
|
71
71
|
**Be prescriptive, not exploratory.** "Use X" not "Consider X or Y."
|
|
72
72
|
|
|
@@ -111,11 +111,11 @@ When researching "best library for X": find what the ecosystem actually uses, do
|
|
|
111
111
|
|
|
112
112
|
## Tool Priority
|
|
113
113
|
|
|
114
|
-
| Priority | Tool
|
|
115
|
-
|
|
116
|
-
| 1st
|
|
117
|
-
| 2nd
|
|
118
|
-
| 3rd
|
|
114
|
+
| Priority | Tool | Use For | Trust Level |
|
|
115
|
+
| -------- | --------- | ------------------------------------------------- | ------------------ |
|
|
116
|
+
| 1st | Context7 | Library APIs, features, configuration, versions | HIGH |
|
|
117
|
+
| 2nd | WebFetch | Official docs/READMEs not in Context7, changelogs | HIGH-MEDIUM |
|
|
118
|
+
| 3rd | WebSearch | Ecosystem discovery, community patterns, pitfalls | Needs verification |
|
|
119
119
|
|
|
120
120
|
**Context7 flow:**
|
|
121
121
|
1. `mcp__context7__resolve-library-id` with libraryName
|
|
@@ -182,11 +182,11 @@ For each WebSearch finding:
|
|
|
182
182
|
|
|
183
183
|
<source_hierarchy>
|
|
184
184
|
|
|
185
|
-
| Level
|
|
186
|
-
|
|
187
|
-
| HIGH
|
|
188
|
-
| MEDIUM | WebSearch verified with official source, multiple credible sources | State with attribution
|
|
189
|
-
| LOW
|
|
185
|
+
| Level | Sources | Use |
|
|
186
|
+
| ------ | ------------------------------------------------------------------ | -------------------------- |
|
|
187
|
+
| HIGH | Context7, official docs, official releases | State as fact |
|
|
188
|
+
| MEDIUM | WebSearch verified with official source, multiple credible sources | State with attribution |
|
|
189
|
+
| LOW | WebSearch only, single source, unverified | Flag as needing validation |
|
|
190
190
|
|
|
191
191
|
Priority: Context7 > Exa (verified) > Firecrawl (official docs) > Official GitHub > Brave/WebSearch (verified) > WebSearch (unverified)
|
|
192
192
|
|
|
@@ -247,18 +247,18 @@ Priority: Context7 > Exa (verified) > Firecrawl (official docs) > Official GitHu
|
|
|
247
247
|
## Standard Stack
|
|
248
248
|
|
|
249
249
|
### Core
|
|
250
|
-
| Library | Version | Purpose
|
|
251
|
-
|
|
252
|
-
| [name]
|
|
250
|
+
| Library | Version | Purpose | Why Standard |
|
|
251
|
+
| ------- | ------- | -------------- | -------------------- |
|
|
252
|
+
| [name] | [ver] | [what it does] | [why experts use it] |
|
|
253
253
|
|
|
254
254
|
### Supporting
|
|
255
|
-
| Library | Version | Purpose
|
|
256
|
-
|
|
257
|
-
| [name]
|
|
255
|
+
| Library | Version | Purpose | When to Use |
|
|
256
|
+
| ------- | ------- | -------------- | ----------- |
|
|
257
|
+
| [name] | [ver] | [what it does] | [use case] |
|
|
258
258
|
|
|
259
259
|
### Alternatives Considered
|
|
260
|
-
| Instead of | Could Use
|
|
261
|
-
|
|
260
|
+
| Instead of | Could Use | Tradeoff |
|
|
261
|
+
| ---------- | ------------- | ------------------------------ |
|
|
262
262
|
| [standard] | [alternative] | [when alternative makes sense] |
|
|
263
263
|
|
|
264
264
|
**Installation:**
|
|
@@ -296,9 +296,9 @@ src/
|
|
|
296
296
|
|
|
297
297
|
## Don't Hand-Roll
|
|
298
298
|
|
|
299
|
-
| Problem
|
|
300
|
-
|
|
301
|
-
| [problem] | [what you'd build] | [library]
|
|
299
|
+
| Problem | Don't Build | Use Instead | Why |
|
|
300
|
+
| --------- | ------------------ | ----------- | ------------------------ |
|
|
301
|
+
| [problem] | [what you'd build] | [library] | [edge cases, complexity] |
|
|
302
302
|
|
|
303
303
|
**Key insight:** [why custom solutions are worse in this domain]
|
|
304
304
|
|
|
@@ -306,13 +306,13 @@ src/
|
|
|
306
306
|
|
|
307
307
|
> Include this section for rename/refactor/migration phases only. Omit entirely for greenfield phases.
|
|
308
308
|
|
|
309
|
-
| Category
|
|
310
|
-
|
|
311
|
-
| Stored data
|
|
312
|
-
| Live service config | [e.g., "25 n8n workflows in SQLite not exported to git"]
|
|
313
|
-
| OS-registered state | [e.g., "Windows Task Scheduler: 3 tasks with 'dev-os' in description"]
|
|
314
|
-
| Secrets/env vars
|
|
315
|
-
| Build artifacts
|
|
309
|
+
| Category | Items Found | Action Required |
|
|
310
|
+
| ------------------- | ----------------------------------------------------------------------------------- | ---------------------------- |
|
|
311
|
+
| Stored data | [e.g., "Mem0 memories: user_id='dev-os' in ~X records"] | [code edit / data migration] |
|
|
312
|
+
| Live service config | [e.g., "25 n8n workflows in SQLite not exported to git"] | [API patch / manual] |
|
|
313
|
+
| OS-registered state | [e.g., "Windows Task Scheduler: 3 tasks with 'dev-os' in description"] | [re-register tasks] |
|
|
314
|
+
| Secrets/env vars | [e.g., "SOPS key 'webhook_auth_header' — code rename only, key unchanged"] | [none / update key] |
|
|
315
|
+
| Build artifacts | [e.g., "scripts/devos-cli/devos_cli.egg-info/ — stale after pyproject.toml rename"] | [reinstall package] |
|
|
316
316
|
|
|
317
317
|
**Nothing found in category:** State explicitly ("None — verified by X").
|
|
318
318
|
|
|
@@ -336,9 +336,9 @@ Verified patterns from official sources:
|
|
|
336
336
|
|
|
337
337
|
## State of the Art
|
|
338
338
|
|
|
339
|
-
| Old Approach | Current Approach | When Changed
|
|
340
|
-
|
|
341
|
-
| [old]
|
|
339
|
+
| Old Approach | Current Approach | When Changed | Impact |
|
|
340
|
+
| ------------ | ---------------- | -------------- | --------------- |
|
|
341
|
+
| [old] | [new] | [date/version] | [what it means] |
|
|
342
342
|
|
|
343
343
|
**Deprecated/outdated:**
|
|
344
344
|
- [Thing]: [why, what replaced it]
|
|
@@ -354,9 +354,9 @@ Verified patterns from official sources:
|
|
|
354
354
|
|
|
355
355
|
> Skip this section if the phase has no external dependencies (code/config-only changes).
|
|
356
356
|
|
|
357
|
-
| Dependency | Required By
|
|
358
|
-
|
|
359
|
-
| [tool]
|
|
357
|
+
| Dependency | Required By | Available | Version | Fallback |
|
|
358
|
+
| ---------- | --------------------- | --------- | -------------- | --------------- |
|
|
359
|
+
| [tool] | [feature/requirement] | ✓/✗ | [version or —] | [fallback or —] |
|
|
360
360
|
|
|
361
361
|
**Missing dependencies with no fallback:**
|
|
362
362
|
- [items that block execution]
|
|
@@ -369,22 +369,22 @@ Verified patterns from official sources:
|
|
|
369
369
|
> Skip this section entirely if workflow.nyquist_validation is explicitly set to false in .planning/config.json. If the key is absent, treat as enabled.
|
|
370
370
|
|
|
371
371
|
### Test Framework
|
|
372
|
-
| Property
|
|
373
|
-
|
|
374
|
-
| Framework
|
|
375
|
-
| Config file
|
|
376
|
-
| Quick run command
|
|
377
|
-
| Full suite command | `{command}`
|
|
372
|
+
| Property | Value |
|
|
373
|
+
| ------------------ | ----------------------------- |
|
|
374
|
+
| Framework | {framework name + version} |
|
|
375
|
+
| Config file | {path or "none — see Wave 0"} |
|
|
376
|
+
| Quick run command | `{command}` |
|
|
377
|
+
| Full suite command | `{command}` |
|
|
378
378
|
|
|
379
379
|
### Phase Requirements → Test Map
|
|
380
|
-
| Req ID | Behavior
|
|
381
|
-
|
|
382
|
-
| REQ-XX | {behavior} | unit
|
|
380
|
+
| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|
|
381
|
+
| ------ | ---------- | --------- | ----------------------------------------------- | ------------ |
|
|
382
|
+
| REQ-XX | {behavior} | unit | `pytest tests/test_{module}.py::test_{name} -x` | ✅ / ❌ Wave 0 |
|
|
383
383
|
|
|
384
384
|
### Sampling Rate
|
|
385
385
|
- **Per task commit:** `{quick run command}`
|
|
386
386
|
- **Per wave merge:** `{full suite command}`
|
|
387
|
-
- **Phase gate:** Full suite green before `/gsd
|
|
387
|
+
- **Phase gate:** Full suite green before `/gsd-verify-work`
|
|
388
388
|
|
|
389
389
|
### Wave 0 Gaps
|
|
390
390
|
- [ ] `{tests/test_file.py}` — covers REQ-{XX}
|
|
@@ -442,11 +442,11 @@ cat "$phase_dir"/*-CONTEXT.md 2>/dev/null
|
|
|
442
442
|
|
|
443
443
|
**If CONTEXT.md exists**, it constrains research:
|
|
444
444
|
|
|
445
|
-
| Section
|
|
446
|
-
|
|
447
|
-
| **Decisions**
|
|
448
|
-
| **Claude's Discretion** | Research options, make recommendations
|
|
449
|
-
| **Deferred Ideas**
|
|
445
|
+
| Section | Constraint |
|
|
446
|
+
| ----------------------- | ----------------------------------------------- |
|
|
447
|
+
| **Decisions** | Locked — research THESE deeply, no alternatives |
|
|
448
|
+
| **Claude's Discretion** | Research options, make recommendations |
|
|
449
|
+
| **Deferred Ideas** | Out of scope — ignore completely |
|
|
450
450
|
|
|
451
451
|
**Examples:**
|
|
452
452
|
- User decided "use library X" → research X deeply, don't explore alternatives
|
|
@@ -469,13 +469,13 @@ Based on phase description, identify what needs investigating:
|
|
|
469
469
|
|
|
470
470
|
A grep audit finds files. It does NOT find runtime state. For these phases you MUST explicitly answer each question before moving to Step 3:
|
|
471
471
|
|
|
472
|
-
| Category
|
|
473
|
-
|
|
474
|
-
| **Stored data**
|
|
475
|
-
| **Live service config**
|
|
476
|
-
| **OS-registered state**
|
|
477
|
-
| **Secrets and env vars**
|
|
478
|
-
| **Build artifacts / installed packages** | What installed or built artifacts still carry the old name and won't auto-update from a source rename?
|
|
472
|
+
| Category | Question | Examples |
|
|
473
|
+
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
474
|
+
| **Stored data** | What databases or datastores store the renamed string as a key, collection name, ID, or user_id? | ChromaDB collection names, Mem0 user_ids, n8n workflow content in SQLite, Redis keys |
|
|
475
|
+
| **Live service config** | What external services have this string in their configuration — but that configuration lives in a UI or database, NOT in git? | n8n workflows not exported to git (only exported ones are in git), Datadog service names/dashboards/tags, Tailscale ACL tags, Cloudflare Tunnel names |
|
|
476
|
+
| **OS-registered state** | What OS-level registrations embed the string? | Windows Task Scheduler task descriptions (set at registration time), pm2 saved process names, launchd plists, systemd unit names |
|
|
477
|
+
| **Secrets and env vars** | What secret keys or env var names reference the renamed thing by exact name — and will code that reads them break if the name changes? | SOPS key names, .env files not in git, CI/CD environment variable names, pm2 ecosystem env injection |
|
|
478
|
+
| **Build artifacts / installed packages** | What installed or built artifacts still carry the old name and won't auto-update from a source rename? | pip egg-info directories, compiled binaries, npm global installs, Docker image tags in a registry |
|
|
479
479
|
|
|
480
480
|
For each item found: document (1) what needs changing, and (2) whether it requires a **data migration** (update existing records) vs. a **code edit** (change how new records are written). These are different tasks and must both appear in the plan.
|
|
481
481
|
|
|
@@ -523,12 +523,12 @@ docker info 2>/dev/null | head -3
|
|
|
523
523
|
```markdown
|
|
524
524
|
## Environment Availability
|
|
525
525
|
|
|
526
|
-
| Dependency | Required By
|
|
527
|
-
|
|
528
|
-
| PostgreSQL | Data layer
|
|
529
|
-
| Redis
|
|
530
|
-
| Docker
|
|
531
|
-
| ffmpeg
|
|
526
|
+
| Dependency | Required By | Available | Version | Fallback |
|
|
527
|
+
| ---------- | ---------------- | --------- | ------- | ----------------------------------- |
|
|
528
|
+
| PostgreSQL | Data layer | ✓ | 15.4 | — |
|
|
529
|
+
| Redis | Caching | ✗ | — | Use in-memory cache |
|
|
530
|
+
| Docker | Containerization | ✓ | 24.0.7 | — |
|
|
531
|
+
| ffmpeg | Media processing | ✗ | — | Skip media features, flag for human |
|
|
532
532
|
|
|
533
533
|
**Missing dependencies with no fallback:**
|
|
534
534
|
- {list items that block execution — planner must address these}
|
|
@@ -597,8 +597,8 @@ List missing test files, framework config, or shared fixtures needed before impl
|
|
|
597
597
|
<phase_requirements>
|
|
598
598
|
## Phase Requirements
|
|
599
599
|
|
|
600
|
-
| ID
|
|
601
|
-
|
|
600
|
+
| ID | Description | Research Support |
|
|
601
|
+
| -------- | ---------------------- | ----------------------------------------------- |
|
|
602
602
|
| {REQ-ID} | {from REQUIREMENTS.md} | {which research findings enable implementation} |
|
|
603
603
|
</phase_requirements>
|
|
604
604
|
```
|
|
@@ -636,11 +636,11 @@ node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" commit "docs($PHASE): resea
|
|
|
636
636
|
`$PHASE_DIR/$PADDED_PHASE-RESEARCH.md`
|
|
637
637
|
|
|
638
638
|
### Confidence Assessment
|
|
639
|
-
| Area
|
|
640
|
-
|
|
641
|
-
| Standard Stack | [level] | [why]
|
|
642
|
-
| Architecture
|
|
643
|
-
| Pitfalls
|
|
639
|
+
| Area | Level | Reason |
|
|
640
|
+
| -------------- | ------- | ------ |
|
|
641
|
+
| Standard Stack | [level] | [why] |
|
|
642
|
+
| Architecture | [level] | [why] |
|
|
643
|
+
| Pitfalls | [level] | [why] |
|
|
644
644
|
|
|
645
645
|
### Open Questions
|
|
646
646
|
[Gaps that couldn't be resolved]
|