feat(researcher): add Runtime State Inventory for rename/refactor phases

Adds a Runtime State Inventory step that fires when a phase involves
renaming, rebranding, refactoring, or migrating strings across a codebase.

The core problem: grep audits find files. They do NOT find runtime state —
ChromaDB collection names, Mem0 user_ids, n8n workflows in SQLite, Windows
Task Scheduler descriptions, pm2 process names, SOPS key names, pip
egg-info directories, etc. These survive a complete file-level rename and
will break the system silently after the code is "done".

Three additions:
1. Pre-Submission Checklist — adds a reminder item so the checklist gate
   catches skipped inventories before RESEARCH.md is committed
2. output_format — adds Runtime State Inventory table to the RESEARCH.md
   template so the section appears in every rename/refactor phase's output
3. execution_flow Step 2.5 — structured investigation protocol with the
   five categories (stored data, live service config, OS-registered state,
   secrets/env vars, build artifacts), explicit examples for each, and the
   canonical question that frames the whole exercise
This commit is contained in:
Eli Herman
2026-03-18 14:49:27 -05:00
parent a9be67f504
commit 3e61c7da94

View File

@@ -194,6 +194,7 @@ Priority: Context7 > Official Docs > Official GitHub > Verified WebSearch > Unve
- [ ] Publication dates checked (prefer recent/current)
- [ ] Confidence levels assigned honestly
- [ ] "What might I have missed?" review completed
- [ ] **If rename/refactor phase:** Runtime State Inventory completed — all 5 categories answered explicitly (not left blank)
</verification_protocol>
@@ -274,6 +275,20 @@ src/
**Key insight:** [why custom solutions are worse in this domain]
## Runtime State Inventory
> Include this section for rename/refactor/migration phases only. Omit entirely for greenfield phases.
| Category | Items Found | Action Required |
|----------|-------------|------------------|
| Stored data | [e.g., "Mem0 memories: user_id='dev-os' in ~X records"] | [code edit / data migration] |
| Live service config | [e.g., "25 n8n workflows in SQLite not exported to git"] | [API patch / manual] |
| OS-registered state | [e.g., "Windows Task Scheduler: 3 tasks with 'dev-os' in description"] | [re-register tasks] |
| Secrets/env vars | [e.g., "SOPS key 'webhook_auth_header' — code rename only, key unchanged"] | [none / update key] |
| Build artifacts | [e.g., "scripts/devos-cli/devos_cli.egg-info/ — stale after pyproject.toml rename"] | [reinstall package] |
**Nothing found in category:** State explicitly ("None — verified by X").
## Common Pitfalls
### Pitfall 1: [Name]
@@ -407,6 +422,26 @@ Based on phase description, identify what needs investigating:
- **Pitfalls:** Common beginner mistakes, gotchas, rewrite-causing errors
- **Don't Hand-Roll:** Existing solutions for deceptively complex problems
## Step 2.5: Runtime State Inventory (rename / refactor / migration phases only)
**Trigger:** Any phase involving rename, rebrand, refactor, string replacement, or migration.
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:
| Category | Question | Examples |
|----------|----------|----------|
| **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 |
| **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 |
| **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 |
| **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 |
| **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 |
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.
**The canonical question:** *After every file in the repo is updated, what runtime systems still have the old string cached, stored, or registered?*
If the answer for a category is "nothing" — say so explicitly. Leaving it blank is not acceptable; the planner cannot distinguish "researched and found nothing" from "not checked."
## Step 3: Execute Research Protocol
For each domain: Context7 first → Official docs → WebSearch → Cross-verify. Document findings with confidence levels as you go.
@@ -460,7 +495,7 @@ List missing test files, framework config, or shared fixtures needed before impl
## Phase Requirements
| ID | Description | Research Support |
|----|-------------|-----------------|
|----|-------------|------------------|
| {REQ-ID} | {from REQUIREMENTS.md} | {which research findings enable implementation} |
</phase_requirements>
```
@@ -556,4 +591,4 @@ Quality indicators:
- **Actionable:** Planner could create tasks based on this research
- **Current:** Year included in searches, publication dates checked
</success_criteria>
</success_criteria>