@proflandrigan/shards 1.1.0

package/src/agents/specific_instructions/analytics_engineer/phases_deep/phase-7.md

@@ -0,0 +1,235 @@
+> **Previous:** phase-6.md confirmed
+> **Next:** phase-8.md (read only after this phase's gate is confirmed)
+
+---
+
+## Deep Phase 7 — Build
+
+**Context checkpoint:** Before building, prompt the user:
+
+"Planning's confirmed — good moment to run `/compact` or `/clear` before we start
+executing. I'll be working from project-specs.md from here. Say the word when
+you're ready."
+
+Wait for any signal from the user before beginning build steps.
+
+**Knowledge re-check:** Follow `.claude/agents/specific_instructions/shared/knowledge_checkpoint.md` before building.
+
+### Incremental testing — checkpoint gates between layers
+
+Follow `.claude/agents/specific_instructions/shared/incremental_testing.md` during this build. Each layer below is a checkpoint seam — after a layer's models all build green and their post-build validation (grain, fan-out, nulls, sample) passes, emit a `kind=checkpoint` gate fence (template below) and wait for user confirmation before advancing to the next layer. Do not batch the entire DAG into a single build and eyeball a pass/fail at the end.
+
+Checkpoint gate fence — emit exactly this shape. Both `::GATE::` and `::ENDGATE::` fences are required, as are all three attributes (`id`, `phase`, `kind`). No prose outside the fence.
+
+```
+::GATE:: id=<agent-name>-phase-<N>-checkpoint-<component> phase=<N> kind=checkpoint
+Component: <human-readable name>
+Test command: <exact command you ran>
+Evidence:
+  - <measured fact 1, e.g. "df.shape = (48211, 47)">
+  - <measured fact 2, e.g. "null rate on join key = 0.00%">
+  - <measured fact 3, e.g. "sample head matches expected schema">
+Status: PASS | FAIL — <one-line summary>
+Next: <what you'll build after this is confirmed>
+Stop here — await explicit confirmation before writing the next component.
+::ENDGATE::
+```
+
+Expected checkpoint gate IDs for this phase (emit in order as you build):
+
+- `analytics-engineer-deep-phase-7-checkpoint-sources` — sources.yml updates validate; source freshness passes.
+- `analytics-engineer-deep-phase-7-checkpoint-staging` — all staging models build green; grain + sample inspection pass per the post-build rubric.
+- `analytics-engineer-deep-phase-7-checkpoint-intermediate` — intermediate models build green; fan-out verification matches Phase 3 predictions.
+- `analytics-engineer-deep-phase-7-checkpoint-marts` — mart/fact models build green; grain / fan-out / PK-FK null / sample checks all pass.
+- `analytics-engineer-deep-phase-7-checkpoint-tests` — singular tests and snapshot models (if present) run green.
+
+The hook blocks all non-read tools while a checkpoint is open. If a checkpoint fails, diagnose and re-emit with updated evidence before advancing. Use the fence body format shown above (Component / Test command / Evidence / Status / Next).
+
+Build in this order:
+1. Source definitions (sources.yml updates)
+2. Staging models
+3. Intermediate models
+4. Mart models
+5. Snapshot models (if SCD Type 2)
+6. Schema files with tests and documentation
+7. Singular test files
+
+For each model:
+- **Join path trace (models with joins):** Before writing SQL for any model that
+  joins tables, trace the join path following
+  `.claude/agents/specific_instructions/shared/join_path_protocol.md`. Compare the
+  predicted output grain against the grain confirmed in Phase 3. If they diverge,
+  fix the design before writing SQL.
+- Write the SQL (CTEs from source to final; use parameterized model references — never hardcoded table names)
+- Write the schema file (model description, column descriptions, all required tests)
+- Run the stack's build/validate command (e.g., `dbt build --select +model_name`) — fix any failures before next model
+- Do not advance to the next model until the current one is green
+- **If UI-Aware Mode is active**: after each model passes validation, re-push the DAG with the completed model highlighted. Use the same `--panel-id` from Phase 4 (e.g., `dag-<project_name>`) so it updates in place. Apply a Mermaid `style` to mark green models (e.g., `style stg_orders fill:#1a3a1a,stroke:#2a6a2a,color:#60a060`)
+- **Post-build validation (per model, after `dbt build` passes):** Run the
+  applicable checks below using `dbt show` or the warehouse CLI. If any check
+  fails, halt and diagnose before advancing to the next model. In a contract-first
+  / no-data environment (Phase 2 Data sufficiency: Insufficient), skip validation
+  queries and note "THEORETICAL — no data to validate" in the build log.
+
+  **Auto-verify mode**: each layer's post-build sweep is a bulk read-only
+  verification stretch. Open `::AUTO-VERIFY:: agent=analytics-engineer phase=7 tool_budget=<N>`
+  at the start of the layer's validation pass and `::ENDAUTO::` before
+  emitting the layer's checkpoint gate. The hook will auto-approve `dbt show`
+  and SELECT-only warehouse-CLI queries while the block is open; `dbt build`
+  and writes still prompt. See `specific_instructions/shared/auto_verify_mode.md`.
+
+  1. **Grain validation** (every model with a stated PK):
+     ```sql
+     select count(*) as total_rows, count(distinct <pk_columns>) as distinct_pks
+     from <model>
+     -- FAIL if total_rows != distinct_pks
+     ```
+  2. **Join fan-out verification** (models with joins — Tier 2+ from
+     `join_path_protocol.md`):
+     ```sql
+     select 'before_join' as stage, count(*) as row_count from <left_model>
+     union all
+     select 'after_join', count(*)
+     from <left_model> join <right_model> on <join_condition>
+     -- FAIL if after > before and diverges from predicted fan-out in Phase 3
+     ```
+  3. **PK/FK null check** (mart and fact models):
+     ```sql
+     select '<column>' as col, count(*) as total,
+       count(<column>) as non_null,
+       round(100.0 * (count(*) - count(<column>)) / nullif(count(*), 0), 2) as null_pct
+     from <model>
+     -- FAIL if PK has any nulls; WARN if FK null_pct > 5%
+     ```
+  4. **Sample output inspection** (every model):
+     `dbt show --select <model> --limit 5` — visually confirm column names,
+     types, and values look correct before moving on.
+
+  Scale to model importance: staging models need only grain + sample; intermediate
+  models add fan-out checks if they contain joins; mart/fact models get the full
+  suite.
+
+**SQL template for staging model** (adapt reference syntax to your stack):
+```sql
+with source as (
+    select * from <source_ref('schema', 'table')>
+    -- e.g., {{ source('schema', 'table') }} in dbt
+),
+
+renamed as (
+    select
+        -- primary key
+        <source_pk_col>     as <entity_id>,
+
+        -- attributes
+        <col_a>             as <standardized_name>,
+        <col_b>::<type>     as <standardized_name>,
+
+        -- metadata
+        _loaded_at
+    from source
+)
+
+select * from renamed
+```
+
+**SQL template for intermediate model** (adapt reference syntax to your stack):
+```sql
+with <left_model> as (
+    select * from <model_ref('stg_or_int_model')>
+    -- e.g., {{ ref('model') }} in dbt
+),
+
+<right_model> as (
+    select * from <model_ref('stg_or_int_model')>
+),
+
+joined as (
+    select
+        -- grain: one row per <statement>
+        <surrogate_key(col_a, col_b)> as <model>_id,
+        -- e.g., {{ dbt_utils.generate_surrogate_key(['col_a', 'col_b']) }} in dbt
+
+        -- dimensions
+        l.<col>,
+        r.<col>,
+
+        -- measures
+        l.<measure_col>
+    from <left_model> as l
+    left join <right_model> as r
+        on l.<join_key> = r.<join_key>
+),
+
+final as (
+    select * from joined
+)
+
+select * from final
+```
+
+**SQL template for mart model** (adapt reference syntax to your stack):
+```sql
+with <source_model> as (
+    select * from <model_ref('int_model')>
+),
+
+<dimension_model> as (
+    select * from <model_ref('dim_model')>
+),
+
+-- <add any other CTEs needed>
+
+final as (
+    select
+        -- grain: one row per <statement>
+        <surrogate_key(col_a, col_b)> as <mart>_id,
+
+        -- dimensions
+        s.<dim_col>,
+        d.<dim_col>,
+
+        -- measures
+        s.<measure_col>,
+
+        -- metadata
+        current_timestamp as _updated_at
+    from <source_model> as s
+    left join <dimension_model> as d
+        on s.<fk_col> = d.<pk_col>
+)
+
+select * from final
+```
+
+### Document Deep Phase 7
+
+```markdown
+---
+
+## Deep Phase 7: Build Log (Analytics Engineer)
+- **Files created:**
+  - <file path>: <description>
+- **Files modified:**
+  - <file path>: <what changed>
+- **Build validation:**
+  - Build result: Pass | Fail — <details>
+  - Tests passing: <N> / <N>
+- **Post-build validation:**
+  | Model | Grain Check | Fan-Out Check | PK/FK Nulls | Sample OK | Notes |
+  |-------|-------------|---------------|-------------|-----------|-------|
+  | <model> | PASS / FAIL | PASS / FAIL / N/A | PASS / WARN / FAIL | Yes / No | <details or "clean"> |
+  - (or "THEORETICAL — no data to validate" if contract-first design)
+- **Deviations from design:** <changes from Phases 4-6 and why, or "none">
+- **Performance notes:** <run time, row counts, anything notable>
+```
+
+::GATE:: id=analytics-engineer-deep-phase-7 phase=7 kind=phase validates=analytics_engineer
+Read this section back to the user. Stop here — do not begin the next phase or output any further content. Wait for the user to explicitly confirm before proceeding. Do not interpret silence or partial agreement as confirmation.
+::ENDGATE::
+
+---
+
+## When this gate is confirmed
+
+Read `.claude/agents/specific_instructions/analytics_engineer/phases_deep/phase-8.md` in full and follow its instructions starting from Deep Phase 8. Do not pre-read further phase files.

package/src/agents/specific_instructions/analytics_engineer/phases_deep/phase-8.md

@@ -0,0 +1,221 @@
+> **Previous:** phase-7.md confirmed
+> **Next:** This is the final phase — follow the Syn sign-off instructions in this phase to close the project.
+
+---
+
+## Deep Phase 8 — Peer Review and Handoff
+
+**Before finalizing**, invoke peer reviews in parallel, then Syn for sign-off.
+
+**If Phase 1 documented "Downstream consumer: Dashboard (BI Engineer)"**, invoke four peer reviews in parallel — Data Analyst, Data Modeller, Data Engineer, and BI Engineer. Otherwise, invoke three (Data Analyst, Data Modeller, Data Engineer).
+
+Tell the user: "Sending this out for peer review before we call it done. Checking with the Data Analyst, Data Modeller, and Data Engineer in parallel..." (add "and BI Engineer" if applicable).
+
+Invoke all applicable reviews in parallel:
+
+```
+Task(
+  subagent_type="data-analyst",
+  description="Business requirements review for [project] mart",
+  prompt="I am the Analytics Engineer shard. I've built the [mart_name] mart for
+  project [project_name]. The project-specs.md is at [file_path].
+
+  Please review and return:
+  1. Does the mart answer the business questions stated in Phase 1? List each
+     question and whether the mart supports it.
+  2. Is the grain ([grain_statement]) usable for the analyst queries that will
+     run against this mart? Is the grain too fine, too coarse, or correct?
+  3. Are there any missing metrics, calculated fields, or dimensions that analysts
+     will immediately need and that are not present?
+  4. Any naming or column conventions that don't match what analysts expect from
+     this project?
+
+  Keep your response focused on business requirements alignment and analyst usability —
+  not implementation details."
+)
+```
+
+```
+Task(
+  subagent_type="data-modeller",
+  description="Grain and entity conformance review for [project] mart",
+  prompt="I am the Analytics Engineer shard. I've built the [mart_name] mart for
+  project [project_name]. The project-specs.md is at [file_path].
+
+  Please review and return:
+  REVIEW mode — run the full validation suite:
+  1. Does the implemented mart match the designed grain from Phase 3?
+     Run a PK uniqueness check on [pk_column] in [mart_model].
+  2. Do the FK relationships hold? Run null checks on [fk_columns].
+  3. Are there any join fan-out issues? Check [specific joins flagged in Phase 3].
+  4. Does the mart conform with other marts in the project? Are there
+     entity conformance issues?
+
+  Return in the standard Data Model Review format."
+)
+```
+
+```
+Task(
+  subagent_type="data-engineer",
+  description="Staging and infrastructure review for [project] mart",
+  prompt="I am the Analytics Engineer shard. I've built the [mart_name] mart for
+  project [project_name]. The project-specs.md is at [file_path].
+
+  Please review and return:
+  1. Are the staging models used by this mart correctly defined? Are there any
+     staging layer issues I've inherited?
+  2. Are the freshness configs sufficient for the mart's refresh cadence requirement
+     ([cadence from Phase 1])?
+  3. Is the incremental strategy appropriate for the expected data volume and
+     query patterns?
+  4. Any pipeline concerns I should flag to the user before we ship this?
+
+  Keep your response focused on staging soundness and infrastructure fit — not
+  the transformation logic itself."
+)
+```
+
+**BI Engineer mart-usability review (only if Phase 1 downstream consumer is "Dashboard (BI Engineer)"):**
+
+```
+Task(
+  subagent_type="bi-engineer",
+  description="Mart usability review for dashboard consumption — [project]",
+  prompt="I am the Analytics Engineer shard. I've built [mart_name] for project [project_name].
+  Grain: [grain statement from Phase 3].
+  Key columns: [column list from Phase 4 model design].
+  Business questions it answers: [from Phase 1].
+  Dashboard consumer: [from Phase 1].
+
+  Please review from a dashboard design perspective:
+  1. Is this grain appropriate for the dashboard queries this mart is meant to support?
+  2. Are the measure columns pre-aggregated at the right level, or will the dashboard
+     need to re-aggregate in ways that create performance or accuracy risk?
+  3. Is there a date dimension / date spine suitable for time-series charts?
+  4. Are there cardinality concerns in the dimension columns (too many values for
+     filter dropdowns)?
+  5. Any column naming or structure concerns that would complicate chart building?
+
+  Keep the review brief and actionable. Return verdict: Suitable | Concerns | Redesign."
+)
+```
+
+Apply the Reviewer Verdict Protocol independently for each reviewer (see shared protocol — `data-analyst`, `data-modeller`, `data-engineer`, `bi-engineer` rows). Address all Halt-tier verdicts before invoking Syn.
+
+**Then invoke Syn for final sign-off:**
+
+Tell the user: "I'm asking Syn to review the full project specs before we ship this..."
+
+```
+Task(
+  subagent_type="syn",
+  description="Final review of analytics engineering specs",
+  prompt="I am the Analytics Engineer shard. I've completed all phases for project
+  [project_name]. Please review the project-specs.md at [file_path] and provide
+  your final review verdict. Peer reviews from Data Analyst, Data Modeller, and
+  Data Engineer are appended to the specs."
+)
+```
+
+Append Syn's review to specs. Present to user.
+
+If Syn's review includes a "Code Review" section with `Code artifacts found: Yes`:
+- Tell the user: "Syn spotted [N] code file(s) it can review. Want a code pass? (y/n)"
+- If yes, invoke:
+
+```
+Task(
+  subagent_type="syn",
+  description="Code review for analytics engineering project",
+  prompt="CODE REVIEW MODE. I am the Analytics Engineer shard. Project: [project_name].
+  Directory: [project_dir]. Please review and fix the code artifacts produced in
+  this project. The project-specs.md is at [file_path] for context."
+)
+```
+
+Append Syn's code review summary to the specs. Present findings to user.
+
+Then:
+1. Run the full DAG using the stack's build command
+2. Spot-check final mart output (row count, spot-check key metrics)
+3. Summarize in 3-5 bullet points
+4. List all files created/modified
+5. Flag limitations and follow-ups
+
+6. **BI dashboard handoff:** See `.claude/agents/specific_instructions/analytics_engineer/bi_engineer_handoff.md` for the full handoff instructions. Note: if Phase 1 documented "Downstream consumer: Dashboard (BI Engineer)", write the handoff file automatically without asking — it is the expected default, not optional.
+
+7. **Data Analyst handoff:** See `.claude/agents/specific_instructions/analytics_engineer/data_analyst_handoff.md` for the full handoff instructions. Note: if Phase 1 documented "Downstream consumer: Direct analyst queries (Data Analyst)", write the handoff file automatically without asking — it is the expected default, not optional.
+
+**Knowledge harvest.** Before closing, extract reusable knowledge from this project.
+Read `.claude/agents/specific_instructions/shared/knowledge_harvest.md` and follow
+the protocol. Present candidates to the user for confirmation before writing.
+
+### Document Deep Phase 8
+
+```markdown
+---
+
+## Deep Phase 8: Peer Review and Handoff (Analytics Engineer)
+- **Data Analyst review:** <summary of findings>
+  - Verdict: Aligned | Concerns raised
+  - Tier: Proceed | Proceed with caveats
+  - Business requirements met: Yes | Partially | No — <gaps>
+  - Grain usability: Correct | Too fine | Too coarse — <notes>
+  - Missing elements: <list or "none">
+  - Reviewer resolution: Approved | User override — <rationale>
+- **Data Modeller review:** <summary of validation results>
+  - Verdict: Sound | Concerns | Revise
+  - Tier: Proceed | Proceed with caveats | Halt
+  - Grain validation: PASS | FAIL — <details>
+  - FK null checks: PASS | FAIL — <details>
+  - Conformance: Sound | Issues — <details>
+  - Reviewer resolution: Approved | Approved on resubmit | User override — <rationale> | Project stopped
+- **Data Engineer review:** <summary of findings>
+  - Verdict: Sound | Concerns
+  - Tier: Proceed | Proceed with caveats
+  - Staging soundness: Sound | Concerns — <details>
+  - Freshness configs: Sufficient | Insufficient — <details>
+  - Incremental strategy: Appropriate | Concerns — <details>
+  - Reviewer resolution: Approved | User override — <rationale>
+- **BI Engineer mart-usability review:** Not applicable — downstream consumer is not a BI dashboard | <summary of findings>
+  - Verdict: Suitable | Concerns | Redesign
+  - Date spine: Present | Missing — <notes>
+  - Aggregation level: Appropriate | Too fine | Too coarse — <notes>
+  - Dimension cardinality: OK | High-cardinality concerns — <details>
+  - Reviewer resolution: Approved | User override — <rationale>
+- **Syn Review:** <included above>
+- **Peer review issues addressed:**
+  - <issue and fix, or "none — all reviews clean">
+- **End-to-end validation:** Pass | Fail — <details>
+- **Spot-check results:** <mart row count, key metric spot-check>
+- **Summary:**
+  1. <plain-language description>
+  2. <plain-language description>
+  3. <plain-language description>
+- **All files created/modified:**
+  - <file path>
+- **Known limitations:**
+  - <limitation>
+- **Follow-up actions:**
+  - <consumer walkthrough, downstream consumer notification, metrics layer, etc.>
+- **Original request fulfilled:** Yes | Partially | No — <explanation>
+- **BI dashboard handoff:** Yes (auto — BI downstream consumer) — data_models/<project_name>/bi_engineer_handoff.md | Yes (user requested) — data_models/<project_name>/bi_engineer_handoff.md | No — user declined | Not applicable — downstream consumer is not a BI dashboard
+- **DA handoff:** Yes (auto — Data Analyst downstream consumer) — data_models/<project_name>/data_analyst_handoff.md | Yes (user requested) — data_models/<project_name>/data_analyst_handoff.md | No — user declined | Not applicable — downstream consumer is not a Data Analyst
+- **Knowledge harvested:**
+  - <title> → .shards/knowledge/<type>/<filename>.md
+  - Or: None — project did not produce reusable knowledge
+- **Status:** Complete
+```
+
+Update specs header status to `Complete`.
+
+::GATE:: id=analytics-engineer-deep-phase-8 phase=8 kind=final
+Read this final section back to the user. Stop here — wait for the user to explicitly confirm the project is closed before wrapping up.
+::ENDGATE::
+
+---
+
+## When this gate is confirmed
+
+This is the final phase. Once Syn returns APPROVED sign-off, the project is complete. Do not read further files.

package/src/agents/specific_instructions/analytics_engineer/phases_quick/index.md

@@ -0,0 +1,19 @@
+# Analytics Engineer — Quick Track Phase Journey
+
+You will work through these phases sequentially. Each phase is in its own file
+under this directory. **Only read the next phase's file after the previous
+phase's gate has been confirmed by the user.** Do not pre-read ahead.
+
+## Phases (Quick Track)
+
+| # | File       | Goal                                                            | Gated |
+|---|------------|-----------------------------------------------------------------|-------|
+| 1 | phase-1.md | Scope the change — affected models, blast radius                 | yes   |
+| 2 | phase-2.md | Implement and validate                                           | final (validated) |
+
+## How to proceed
+
+1. You are now oriented. Do not read phase files beyond the current one.
+2. Start Quick Phase 1 now: Read `phase-1.md` in full and follow its instructions.
+3. When a phase's gate is confirmed, that phase's file will tell you which file to read next.
+4. If the Quick track escalates to Deep (per the escalation rules in phase-2.md), load the phases_deep/ directory.

package/src/agents/specific_instructions/analytics_engineer/phases_quick/phase-1.md

@@ -0,0 +1,47 @@
+> **Previous:** This is the first phase of the Analytics Engineer Quick Track.
+> **Next:** phase-2.md (read only after this phase's gate is confirmed)
+
+---
+
+## Quick Phase 1 — Scope the Change
+
+Goal: Understand which models are affected and what specifically changes.
+
+Ask about:
+- Which model(s) are affected? (exact file path or model name)
+- Current state vs. desired state?
+- Downstream models that depend on affected columns?
+- **What should still be true after this change?** Ask for specific regression checks / invariants the user expects to hold once the change lands (e.g. "downstream row counts unchanged", "no new nulls in `order_id`", "the metric still reconciles with finance's number").
+
+Then:
+1. Read the model file and its .yml schema
+2. Trace downstream dependencies via ref()
+3. Assess blast radius of the change
+4. Present the change plan
+
+### Document Quick Phase 1
+
+```markdown
+---
+
+## Quick Phase 1: Change Scope (Analytics Engineer)
+- **Affected model(s):** <model name(s) and file path(s)>
+- **Current state:** <what exists now>
+- **Desired state:** <what should exist after>
+- **Downstream dependencies:** <models referencing affected columns or "none">
+- **Blast radius:** Isolated | Minor (<3 models) | Significant (3+)
+- **Change plan:**
+  - <file>: <what changes>
+- **Acceptance criteria (must hold after change):**
+  - <criterion 1>
+```
+
+::GATE:: id=analytics-engineer-quick-phase-1 phase=1 kind=phase validates=analytics_engineer
+Read this section back to the user. Stop here — do not begin the next phase or output any further content. Wait for the user to explicitly confirm before proceeding. Do not interpret silence or partial agreement as confirmation.
+::ENDGATE::
+
+---
+
+## When this gate is confirmed
+
+Read `.claude/agents/specific_instructions/analytics_engineer/phases_quick/phase-2.md` in full and follow its instructions starting from Quick Phase 2. Do not pre-read further phase files.

package/src/agents/specific_instructions/analytics_engineer/phases_quick/phase-2.md

@@ -0,0 +1,78 @@
+> **Previous:** phase-1.md confirmed
+> **Next:** This is the final phase of the Quick Track — follow the escalation rules if scope grew, otherwise close the project.
+
+---
+
+## Quick Phase 2 — Implement and Validate
+
+**Context checkpoint:** Before building, prompt the user:
+
+"Planning's locked — good moment to run `/compact` or `/clear` before we start
+executing. I'll be working from project-specs.md from here. Say the word when
+you're ready."
+
+Wait for any signal from the user before beginning build steps.
+
+**Knowledge re-check:** Follow `.claude/agents/specific_instructions/shared/knowledge_checkpoint.md` before building.
+
+1. Implement the change in the model SQL and schema file
+2. Update downstream models if column names or types changed
+3. Run the stack's build/validate command to validate
+4. **Post-build validation:** After the build passes, run grain validation
+   (`count(*) vs count(distinct pk)`) on each changed model. For models with
+   joins, run the fan-out check from `join_path_protocol.md` Tier 2+. Run
+   `dbt show --select <model> --limit 5` to confirm output looks right.
+   If any check fails, fix before proceeding. Skip if no-data environment.
+5. Summarize what changed
+
+**Knowledge harvest.** Before closing, extract reusable knowledge from this project.
+Read `.claude/agents/specific_instructions/shared/knowledge_harvest.md` and follow
+the protocol. Present candidates to the user for confirmation before writing.
+
+### Document Quick Phase 2
+
+```markdown
+---
+
+## Quick Phase 2: Implementation (Analytics Engineer)
+- **Files changed:**
+  - <file path>: <what changed>
+- **Downstream updates:** <files updated or "none needed">
+- **Validation result:** Pass | Fail — <details>
+- **Tests passing:** <N> / <N>
+- **Post-build validation:** PASS | FAIL | SKIPPED (no data) — <details>
+- **Follow-up needed:** Yes / No — <if yes, describe>
+- **Knowledge harvested:**
+  - <title> → .shards/knowledge/<type>/<filename>.md
+  - Or: None — project did not produce reusable knowledge
+- **Status:** Complete
+```
+
+Update specs header status to `Complete`.
+
+::GATE:: id=analytics-engineer-quick-phase-2 phase=2 kind=final
+Read this section back to the user. Stop here — wait for the user to explicitly confirm the change is correct before wrapping up.
+::ENDGATE::
+
+---
+
+## Quick-to-Deep Escalation
+
+If during Quick Phase 1 or Quick Phase 2 the scope grows beyond a quick change (e.g., blast radius is Significant, new models are needed, or the change requires a full redesign), escalate to the Deep track:
+
+1. **Announce:** Tell the user exactly what triggered the escalation and why the Quick track can't handle it.
+2. **Propose:** Recommend switching to the Deep track within the same Analytics Engineer session.
+3. **Preserve context:** Write an `## Escalation Brief` section to `project-specs.md` following the format defined in `.claude/agents/specific_instructions/shared/behavioral_rules.md`. Set the **Target agent** to `Analytics Engineer (Deep Track)`.
+4. **Hand off:** Tell the user:
+
+> "This has grown beyond a quick change — [specific trigger]. I recommend switching to the **Deep track** for a full pipeline design.
+>
+> I've written an Escalation Brief to `project-specs.md` so nothing is lost. I'll load the Deep track phases now and pick up from the brief."
+
+After the user confirms, read `.claude/agents/specific_instructions/analytics_engineer/phases_deep/index.md` to orient on the Deep Track phases, then read `.claude/agents/specific_instructions/analytics_engineer/phases_deep/phase-1.md` and resume from Deep Phase 1, treating the Escalation Brief as prior context.
+
+---
+
+## When this gate is confirmed
+
+This is the final phase of the Quick Track. If escalation to Deep Track is required (per the Quick-to-Deep Escalation section in this phase), read `.claude/agents/specific_instructions/analytics_engineer/phases_deep/index.md` and continue from there. Otherwise, the project is complete.