SoundMindsAI · SoundMindsAI · May 28, 2026 · May 28, 2026 · May 28, 2026 · May 28, 2026
@@ -12,7 +12,7 @@ user-invocable: true
 # Bug Fix — drive a medium-sized bug from repro to committed fix
 
 You take a bug that's been captured as a `bug_*` folder under
-`docs/02_product/planned_features/` and drive it through CLAUDE.md's
+`docs/00_overview/planned_features/` and drive it through CLAUDE.md's
 **Bug Fix Protocol**. The skill produces two artifacts: a focused
 `bug_fix.md` design doc that lives next to the original `idea.md`, AND
 the actual code change committed on a feature branch. The next step
@@ -44,7 +44,7 @@ running `/pipeline`.
 
 ## Inputs
 
-- **Path to the bug folder** (preferred — `docs/02_product/planned_features/bug_<slug>/`) or the `idea.md` inside it.
+- **Path to the bug folder** (preferred — `docs/00_overview/planned_features/bug_<slug>/`) or the `idea.md` inside it.
 - **Project context (always read first):** `CLAUDE.md`, `architecture.md`, `state.md`.
 - **Bug Fix Protocol section** of `CLAUDE.md` — the 6-step protocol is the spine of this skill's workflow.
 - **The /idea-preflight output** if it was run on this bug recently — the patches it landed are the starting point for the `bug_fix.md`.
@@ -187,7 +187,7 @@ Now you write the artifact and the code. The artifact and the
 implementation reference each other; write them in parallel, not the
 artifact first then the code.
 
-1. **Write `bug_fix.md`** at `docs/02_product/planned_features/<bug_folder>/bug_fix.md`
+1. **Write `bug_fix.md`** at `docs/00_overview/planned_features/<bug_folder>/bug_fix.md`
    using the template below. Keep it tight — the target is ~80 lines.
    Anything that would push past 150 lines is a signal the bug should
    have been a feature; escalate to /pipeline. **The 150-line cap

@@ -238,7 +238,7 @@ Classify all findings from both passes (including completeness and route relevan
 **For UI Bugs (code is right, UI is wrong):**
 Create a bug tracking file:
 ```
-docs/02_product/planned_features/bug_<description>/idea.md
+docs/00_overview/planned_features/bug_<description>/idea.md
 ```
 Following the idea template with:
 - **Status:** `Bug — identified by guide-gen visual audit`
@@ -250,7 +250,7 @@ Following the idea template with:
 **For Missing Features (intentional gap, not a bug):**
 Create a feature tracking file:
 ```
-docs/02_product/planned_features/<feature_name>/idea.md
+docs/00_overview/planned_features/<feature_name>/idea.md
 ```
 
 **For Spec Issues:**

@@ -36,7 +36,7 @@ The skill never commits or opens a PR — that's the user's call. Patches land a
 
 - **`$ARGUMENTS`** — path to a single `idea.md`. If omitted, fall back to the file the user most recently opened in the IDE (`<ide_opened_file>` context tag), or ask.
 - **Project context (always read first):** `CLAUDE.md`, `architecture.md`, `state.md`.
-- **Convention reference:** `docs/02_product/planned_features/feature_templates/README.md` for folder-prefix taxonomy.
+- **Convention reference:** `docs/00_overview/planned_features/feature_templates/README.md` for folder-prefix taxonomy.
 
 ## Workflow
 
@@ -87,15 +87,15 @@ If a rename is recommended, propose the new name with one-line rationale and 2
 
 ### Step 6 — Cross-check siblings + recently implemented features
 
-1. `ls docs/02_product/planned_features/` — for any sibling whose name overlaps the idea's domain, check whether the two coordinate or conflict. The idea's "Relationship to other work" section should mention each sibling that touches the same table/service/UI surface.
+1. `ls docs/00_overview/planned_features/` — for any sibling whose name overlaps the idea's domain, check whether the two coordinate or conflict. The idea's "Relationship to other work" section should mention each sibling that touches the same table/service/UI surface.
 2. `git log --since="<idea date>" --oneline -- docs/00_overview/implemented_features/` — list features that shipped after the idea was written. For each, ask: does its ship retire any deferral rationale in this idea? Does it create any new precedent the idea should reference (e.g. scheduler 5-touch-point checklist after the worker-runtime work shipped)?
 3. Note any sibling that the idea should explicitly coordinate with for ordering (not blocking — coordinate-only is the common case).
 
 ### Step 7 — Cross-check against CLAUDE.md absolute rules
 
 For each claim in the idea, mentally walk the project's "Absolute Rules — Never Violate" section. RelyLoop's CLAUDE.md (when it exists per `infra_foundation`) will codify these; until then, derive from the umbrella spec + `docs/01_architecture/`. Common rules to check:
 
-- Adding a migration? → reversible downgrade + idempotency guards mentioned (per [`infra_foundation/feature_spec.md`](../../docs/02_product/planned_features/infra_foundation/feature_spec.md) FR-5).
+- Adding a migration? → reversible downgrade + idempotency guards mentioned (per [`infra_foundation/feature_spec.md`](../../docs/00_overview/planned_features/infra_foundation/feature_spec.md) FR-5).
 - Adding a webhook handler (e.g., `/webhooks/github`)? → signature verification on raw body + idempotency.
 - Adding a state-machine transition (e.g., `studies.status`)? → routed through the centralized service-layer guard (`backend/services/study_state.py`); direct ORM writes raise.
 - Adding a `<select>` / dropdown / status badge? → option list grounded in a backend source-of-truth file (Pydantic `Literal[...]`, `frozenset`, or DB CHECK) with a `// Values must match <path>` comment.
@@ -110,7 +110,7 @@ If the idea quietly violates any of these, that's a hard blocker, not a "fix-up.
 
 Scan the idea for "Option A vs Option B" forks. For each:
 
-- If the fork has a clear default and the idea doesn't pick one, propose locking it. Use the same "(locked)" header pattern this codebase uses; structure the locked decisions as a Decision-log entry similar to the §19 sections in the existing MVP1 feature specs under `docs/02_product/planned_features/`.
+- If the fork has a clear default and the idea doesn't pick one, propose locking it. Use the same "(locked)" header pattern this codebase uses; structure the locked decisions as a Decision-log entry similar to the §19 sections in the existing MVP1 feature specs under `docs/00_overview/planned_features/`.
 - If the fork genuinely needs user input (UX call, product call, business call), keep it but reframe in the "Open questions for /spec-gen" section with a recommended default so /spec-gen doesn't start from zero.
 
 A "locked decision" is a decision someone reading the idea cold can act on without re-litigating.

@@ -218,7 +218,7 @@ If the story added or changed any of the following, you MUST run the actual comm
 | Migration via `make migrate` / `make migrate-create` | Run the actual `make` target; confirm the file landed at the expected host path with the expected revision ID format |
 | Endpoint exposed publicly (FastAPI router, Compose port, etc.) | Hit the endpoint from the documented client environment (host shell, browser, sibling container) and confirm response shape |
 
-**Why this gate exists** (canonical incident, infra_foundation PR #4 first-run testing, 2026-05-09): five integration-boundary bugs shipped through CI green and surfaced in the first 30 minutes of operator first-run testing — a stale image missing a Python dep, a stub secret without a driver prefix, two Make targets that assumed env vars only present in CI, and an alembic post-write hook that crashed inside the runtime image (no dev deps). Every one would have been caught by literally running `make up` once before declaring stories complete. CI's hermetic test layers cannot substitute for end-to-end operator-path execution. See [`docs/02_product/planned_features/infra_ci_smoke_makeup/idea.md`](../../../docs/02_product/planned_features/infra_ci_smoke_makeup/idea.md) for the systemic CI follow-up.
+**Why this gate exists** (canonical incident, infra_foundation PR #4 first-run testing, 2026-05-09): five integration-boundary bugs shipped through CI green and surfaced in the first 30 minutes of operator first-run testing — a stale image missing a Python dep, a stub secret without a driver prefix, two Make targets that assumed env vars only present in CI, and an alembic post-write hook that crashed inside the runtime image (no dev deps). Every one would have been caught by literally running `make up` once before declaring stories complete. CI's hermetic test layers cannot substitute for end-to-end operator-path execution. See [`docs/00_overview/planned_features/infra_ci_smoke_makeup/idea.md`](../../../docs/00_overview/planned_features/infra_ci_smoke_makeup/idea.md) for the systemic CI follow-up.
 
 If you cannot run the operator-path verification (e.g., no Docker daemon available in the agent environment), **escalate to the user** rather than skip — do not silently mark the story complete.
 
@@ -552,7 +552,7 @@ For every new `event_type` literal introduced by the diff (grep `git diff` for `
 1. Read the feature spec's "Phase boundaries" and "Scope" sections. Identify any phases that were NOT included in the implementation plan (e.g., the plan covers Phase 1 but the spec defines Phase 2 work).
 2. For each deferred phase, check whether a tracking file already exists:
    - `glob` for `*idea*.md` or `*phase*_idea.md` in the feature's `planned_features` directory
-3. If no tracking file exists for a deferred phase, create one at `docs/02_product/planned_features/<feature_dir>/phase<N>_idea.md` with:
+3. If no tracking file exists for a deferred phase, create one at `docs/00_overview/planned_features/<feature_dir>/phase<N>_idea.md` with:
    - **Date** and **Status** (`Idea — deferred from Phase <N-1> implementation`)
    - **Origin** — pointer to the spec file and line numbers where the deferred work is defined
    - **Depends on** — which phase must be merged first
@@ -589,7 +589,7 @@ Walk back through this implementation session and ask:
 5. **Did I think "I should fix that someday" about anything**, even briefly? File the someday now.
 6. **Did I notice during implementation any operator-judgment-shaped question that has no canonical answer in the current docs?** Examples: *"What happens if I X?"* / *"Should I trust Y in case Z?"* / *"My pipeline shows N — is that a bug or expected?"* If yes, either (a) draft the entry directly under `ui/src/lib/faq.ts` in this PR (preferred — adds the answer where operators will look for it), OR (b) file a focused `chore_faq_<slug>/idea.md` capturing the question + draft answer + the spec/AC citation that backs the answer. Tooltips and the glossary are NOT the right surface — they're definitional, not judgment-shaped.
 
-For each, create `docs/02_product/planned_features/<bug_|chore_|infra_>_<slug>/idea.md` per [feature_templates/idea-template.md](../../../docs/02_product/planned_features/feature_templates/idea-template.md). Origin field MUST point at the PR or story that surfaced the observation, so the trace stays intact.
+For each, create `docs/00_overview/planned_features/<bug_|chore_|infra_>_<slug>/idea.md` per [feature_templates/idea-template.md](../../../docs/00_overview/planned_features/feature_templates/idea-template.md). Origin field MUST point at the PR or story that surfaced the observation, so the trace stays intact.
 
 **If you have nothing to file, state explicitly: "Tangential observations sweep: none found." in your end-of-step summary.** Silence is suspicious — the sweep is supposed to find things.
 
@@ -869,7 +869,7 @@ Send to GPT-5.5 with the full implementation plan. This catches cross-story issu
 6. **Check for unimplemented phase idea files:**
    Before moving the folder, check for any `phase*_idea.md` files in the feature directory:
    ```bash
-   ls docs/02_product/planned_features/<feature_dir>/phase*_idea.md 2>/dev/null
+   ls docs/00_overview/planned_features/<feature_dir>/phase*_idea.md 2>/dev/null
    ```
    - If any `phase*_idea.md` files exist, **STOP** — do not move the folder.
    - Report the found files to the user and ask for instructions. The folder contains future work that has not been implemented yet, so moving it to `implemented_features/` would be incorrect.
@@ -878,7 +878,7 @@ Send to GPT-5.5 with the full implementation plan. This catches cross-story issu
 
 7. **Move feature folder to implemented_features:**
    ```bash
-   mv docs/02_product/planned_features/<feature_dir> \
+   mv docs/00_overview/planned_features/<feature_dir> \
       docs/00_overview/implemented_features/<YYYY_MM_DD>_<short_name>/
    ```
    - Date prefix uses the completion date (today).
@@ -1028,7 +1028,7 @@ Some stories involve manual configuration outside the codebase (GitHub App regis
 
 1. **Never commit to main.** Always use a feature branch.
 2. **Never skip a verification gate.** If lint fails, fix it. If tests fail, fix them. No `--no-verify`.
-3. **Never implement beyond the story scope. Capture, don't carry.** If you see a bug or improvement opportunity that's orthogonal to the current story, do NOT fix it in this story's commit AND do NOT just "note it for later" in conversation memory. **Create an idea file immediately** at `docs/02_product/planned_features/<bug_|chore_|infra_>_<slug>/idea.md` per the [tangential-discoveries protocol in CLAUDE.md](../../../CLAUDE.md#tangential-discoveries--capture-as-idea-files-immediately). Idea files surface in `/pipeline --status` and persist across sessions; chat-noticings evaporate. Step 1.5 below ("Tangential observations sweep") flushes any uncaptured noticings before push as a safety net, but the discipline is to capture inline as you notice.
+3. **Never implement beyond the story scope. Capture, don't carry.** If you see a bug or improvement opportunity that's orthogonal to the current story, do NOT fix it in this story's commit AND do NOT just "note it for later" in conversation memory. **Create an idea file immediately** at `docs/00_overview/planned_features/<bug_|chore_|infra_>_<slug>/idea.md` per the [tangential-discoveries protocol in CLAUDE.md](../../../CLAUDE.md#tangential-discoveries--capture-as-idea-files-immediately). Idea files surface in `/pipeline --status` and persist across sessions; chat-noticings evaporate. Step 1.5 below ("Tangential observations sweep") flushes any uncaptured noticings before push as a safety net, but the discipline is to capture inline as you notice.
 4. **Always read before editing.** Never modify a file you haven't read in this session.
 5. **Always use GPT-5.5 for cross-model review.** Model ID: `gpt-5.5`. Never substitute gpt-4o.
 6. **Always update the plan tracker** after completing a story.

@@ -34,7 +34,7 @@ Before starting, determine which mode applies based on the user's request and th
   - **Generate**: single path to the approved feature spec (e.g., `docs/.../feature_spec.md`)
   - **Review / Review & Patch**: single path to the existing plan (e.g., `docs/.../implementation_plan.md`)
   - **Reconcile**: two paths separated by a space — spec first, then plan (e.g., `docs/.../feature_spec.md docs/.../implementation_plan.md`)
-- **Plan template**: `docs/02_product/planned_features/feature_templates/implementation-plan-template.md`
+- **Plan template**: `docs/00_overview/planned_features/feature_templates/implementation-plan-template.md`
 - **Project context**: `CLAUDE.md`, `architecture.md`, `state.md`
 
 ---
@@ -48,7 +48,7 @@ Read these files in order:
 1. `CLAUDE.md` — project conventions, absolute rules, data model, stack
 2. `architecture.md` — system design, boundaries, critical flows, frontend page structure
 3. `state.md` — current priorities, recent changes, known debt, Alembic head
-4. `docs/02_product/planned_features/feature_templates/implementation-plan-template.md` — the output template
+4. `docs/00_overview/planned_features/feature_templates/implementation-plan-template.md` — the output template
 5. The approved feature spec at $ARGUMENTS — every FR, AC, data model change, API contract, and test requirement
 
 ### Step 2: Codebase exploration
@@ -255,7 +255,7 @@ Write the final plan to the appropriate location:
 
 1. Read the spec's "Phase boundaries" section. Identify any phases NOT covered by this implementation plan.
 2. For each deferred phase, check whether a tracking file already exists (`glob` for `*idea*.md` or `*phase*_idea.md` in the feature directory).
-3. If no tracking file exists, create one at `docs/02_product/planned_features/<feature_dir>/phase<N>_idea.md` following the `idea.md` template pattern (see `docs/02_product/planned_features/feature_templates/idea-template.md`). Include:
+3. If no tracking file exists, create one at `docs/00_overview/planned_features/<feature_dir>/phase<N>_idea.md` following the `idea.md` template pattern (see `docs/00_overview/planned_features/feature_templates/idea-template.md`). Include:
    - Origin pointer to the spec file and line numbers
    - The deferred FRs with enough context to generate a future spec/plan
    - Why the work was deferred (from the spec's phase boundary rationale)
@@ -277,7 +277,7 @@ Present proposed doc updates to the user for approval before writing.
 
 **This step is MANDATORY in Generate mode.** Update the `pipeline_status.md` file in the feature directory to record the plan stage completion. This file enables the `/pipeline` orchestrator to detect what stage a feature is at and resume automatically.
 
-Update the `## Plan` section in `docs/02_product/planned_features/<feature_dir>/pipeline_status.md`:
+Update the `## Plan` section in `docs/00_overview/planned_features/<feature_dir>/pipeline_status.md`:
 
 ```markdown
 ## Plan