Workflow Guide

Workflows

These are not tutorials. Tutorials teach you the tool. Workflows show you how someone with professional intent would actually use it — with context, trade-offs, and the small decisions that matter.

These are not tutorials. Tutorials teach you the tool. Workflows show you how someone with professional intent would actually use it — with context, trade-offs, and the small decisions that matter.

Each scenario is self-contained. You don't need to read them in order. Read the ones that match what you're trying to do.

Scenario 1: Building a New Data Pipeline from Scratch

The situation: You have a requirements brief and a blank Snowflake schema. You know what you're building but haven't written a line of SQL yet. This is the full CocoBrew lifecycle applied to a real project.

Assumptions: CocoPlus initialized ($pod init done), Assist Mode active ($cocoplus on done).

Step 1: Specify what you're building


$spec

The Spec phase opens a structured dialogue. It asks you questions:

Answer these questions with specificity. "Build a customer churn prediction pipeline" is a goal. "Deliver a daily-refreshed table in ANALYTICS.ML_OUTPUTS with churn probability scores per customer ID, consumed by the BI team's Cortex Analyst semantic model" is a spec.

The Spec phase will push back if your answers are vague. It's not being difficult — it's preventing you from arriving at Plan with a spec that leaves half the decisions undone.

Output: .cocoplus/lifecycle/spec.md + git commit.

Step 2: Plan the work


$cocoplus plan

The Plan phase reads your spec.md, invokes CocoHarvest to decompose the work into stages, assigns each stage to the appropriate specialist persona, and generates flow.json — your execution pipeline.

Then it enters Coco's native plan mode. You review the generated plan. You see every proposed stage, every persona assignment, every checkpoint. This is the approval gate — the moment where the developer and the system agree on what's about to happen.

Read the plan carefully. If a stage is wrong — wrong persona, wrong sequencing, wrong scope — correct it here. Editing flow.json before you approve is allowed and expected. The point is that you understand and agree with the plan before any execution begins.

When you approve, CocoPlus writes plan.md and creates the commit: feat(plan): approved execution plan v1.

Step 3: Before you build — optionally challenge the plan


$secondeye

This is optional. But if you're building something complex, irreversible, or high-stakes — run it.

SecondEye spawns three critics in parallel. Each one reads the same plan from a different angle:

You get a single aggregated report with findings classified as Critical, Advisory, or Observation. Critical findings create a soft gate — you must either revise the plan or run $secondeye acknowledge to confirm you've seen the risks and are proceeding intentionally.

The time SecondEye saves is the time you won't spend mid-build discovering that a foundational assumption was wrong.

Step 4: Build


$cocoplus build

The Build phase reads flow.json and begins execution. For a multi-stage parallel plan, CocoHarvest spawns persona subagents in isolated git worktrees — each running independently, each committing its own stage artifacts.

While it runs: You can monitor progress with $flow status. Each stage shows its status (pending, running, complete, failed), how long it's been running, and whether its checkpoints are satisfied.

If a stage fails: The failure reason is written to flow.json. Dependent stages don't start. You can review the failure, fix the issue, and resume from the failed stage with $flow resume [stage-id] — which first validates that all prior stages' checkpoints are intact.

Checkpoint validation is not optional. CocoHarvest will not advance to the next stage until the current stage's output files exist and pass validation. This is what prevents a partially-built pipeline from silently proceeding as if complete.

Each completed stage creates a git commit: build(<stage-id>): <name> — checkpoints verified. By the time Build completes, you have a granular, auditable history of what was built and in what order.

Step 5: Test


$cocoplus test

The Test phase runs validation against your spec's success criteria — not against a developer's mental model of what success looks like. If your spec said the output table must have non-null churn scores for all active customers, the Test phase checks that. If your spec said the pipeline must complete in under 15 minutes, the Test phase measures that.

Tests are SQL-based where the artifact is a table or view. Notebook-based where the artifact is a Snowpark notebook. File-existence-based where the artifact is a generated schema or procedure.

Test results are recorded in .cocoplus/lifecycle/test.md linked back to their spec criteria. Pass/fail is not the only output — the test record is what you review in the next phase.

Step 6: Review


$cocoplus review

The Review phase aggregates three sources of findings and produces a structured quality report:

Code Quality Advisor findings — every SQL file written during Build has been reviewed for performance anti-patterns, correctness issues, governance gaps, and cost risks. If you had the quality advisor on during Build, these findings have already been accumulating. Review surfaces them in their entirety.

CocoCupper findings — the background analyst read what happened during the Build and Test sessions and identified patterns, anti-patterns, and decisions worth noting. These show up here too.

Spec compliance — a systematic check: does the built artifact match what the spec said we were building?

Each finding is classified: must-fix (blocks Ship), should-fix (recommended before Ship), or consider (worth knowing, not blocking). You review the findings and make decisions. Review does not ship anything — it equips you to decide whether you're ready to.

Step 7: Ship


$cocoplus ship

Ship is gated on review completion with no open must-fix items. If must-fix items are open, $cocoplus ship refuses — not with an error, but with a list of exactly what's blocking it and how to resolve each item.

When you ship:

The git history at this point is a complete, legible record of the project: spec commit, plan commit, per-stage build commits, test commit, review commit, ship commit. Every decision traceable. Every artifact versioned.

What if you need to go back?


$rewind [step-id]

CocoPlus tracks CocoBrew phase commits in git. $rewind shows you the target state, tells you what would be discarded, and performs the rollback after confirmation — using soft resets that preserve history rather than destructive rewrites.


$fork [branch-name]

If you want to explore a different approach without discarding your current work, $fork creates an isolated git worktree on a fork/<branch-name> branch. Experiment freely. If the fork works, you can bring it back. If it doesn't, discard it and your main work is untouched.

Scenario 2: Quick Expert Consultation with a Persona

The situation: You're mid-session and you need specific expertise — not a full build, just a review or a pointed question. This is direct persona invocation.

You have a stored procedure that's running slow and you need a performance review:


$de Review this stored procedure for performance issues

The Data Engineer persona activates. It reads the procedure (you can paste it in or reference the file), analyzes it against Snowflake execution semantics, identifies issues — full table scans, non-SARGable predicates, unnecessary VARIANT parsing, whatever it finds — and explains its reasoning.

If you want it to continue and fix what it found:


$de --continue Fix the issues you identified

The --continue flag passes the full conversation context to the persona, so it knows exactly what it analyzed and can proceed without re-reading the problem statement.

For a governance review before touching production data:


$dst Review the proposed schema changes for governance compliance

The Data Steward operates in plan mode — it will analyze, recommend, and document, but it will not execute SQL against your Snowflake environment. That's the design. Governance advice and execution are different responsibilities.

For a strategic architecture question:


$cdo What are the architectural trade-offs of building this as a Cortex Analyst model versus a stored procedure?

CDO uses Opus. The answer will be deeper and more strategic than what Sonnet would produce. This costs more tokens. It's the right tool for a decision that will constrain your project for months.

Model override for a quick, cheap answer on a simpler question:


$da --model haiku Give me the top 10 customers by revenue in the last 30 days

The Data Analyst on Haiku for a quick exploratory query. Fast, cheap, exactly proportionate to the task.

Scenario 3: Parallel Build with CocoHarvest

The situation: Your plan has multiple independent workstreams — schema layer, semantic model, notebook pipeline, and governance documentation — that don't depend on each other and can run simultaneously.

After your plan is approved, $cocoplus build detects that CocoHarvest should handle this. It identifies the independent workstreams and spawns them in isolated git worktrees:

All four run simultaneously. None of them can see the others' work-in-progress — they're in isolated worktrees. Their only shared reference is the spec and plan files you approved.

Monitor progress:


$flow status

You'll see all four stages with live status indicators. When a stage completes, CocoHarvest validates its checkpoints. When all stages complete, it merges the worktree branches back and creates the final stage commits.

If you want to override the model for the entire pipeline:


$cocoplus build --model opus

This sets a pipeline-level default (Tier 2). Any stage that CocoHarvest didn't assign a specific model gets this one instead. Stages that CocoHarvest explicitly assigned (Tier 3) are unaffected.

If one stage fails:


$flow status
# identifies stage-003 as failed with reason: "NotebookExecute timeout"

$flow resume stage-003

$flow resume validates that stages 001, 002, and 004 have their checkpoints intact before letting stage-003 restart. You are not blindly resuming into an uncertain state — you are resuming into a validated one.

Scenario 4: SecondEye Before a High-Stakes Plan

The situation: You've just planned a schema migration that will reorganize three production-adjacent schemas. The plan looks right to you, but it's the kind of thing you don't want to discover halfway through was missing a dependency.

Plan is approved. Before running $cocoplus build:


$secondeye

Three critics fire in parallel on your plan.md. After they complete — typically a minute or two — you receive an aggregated report.

Reading the report: Start with Critical findings. These are findings where at least the model that raised them believes there is a fundamental issue that materially increases execution risk. If a finding is marked [Consensus], two or three models flagged the same issue — take that seriously.

A realistic Critical finding for a schema migration might read:

[Consensus] Plan assumes all downstream views can be recreated from DDL in spec.md, but spec.md does not include view definitions. If any views have non-standard column aliases or UNION constructs, recreation will fail silently. Recommend validating view DDL extraction in a pre-build step.

This is information you needed before $cocoplus build started running.

If you agree with the Critical findings and want to address them:

Update plan.md (or run $cocoplus plan again to re-generate), then re-run $secondeye. The previous report is superseded automatically when you re-run $cocoplus plan.

If you've reviewed the Critical findings and are accepting the risk intentionally:


$secondeye acknowledge

You'll be shown the Critical findings one more time. Confirm, and the soft gate clears. This acknowledgment is recorded in the report metadata — if anyone ever asks why you proceeded with known risks, the record exists.

Reviewing a specific artifact instead of the default plan:


$secondeye --artifact spec

SecondEye can critique any lifecycle artifact. Before you finalize your spec and move to planning, a SecondEye pass on spec.md catches assumptions and missing criteria that will become expensive problems later.


$secondeye --artifact review

Before shipping — run SecondEye against the Review phase output to validate that the review findings are comprehensive.

Scenario 5: Returning to a Project After Time Away

The situation: You've been away from this project for a week. You need to pick up exactly where you left off without spending twenty minutes re-reading your own code.


$pod resume

This is what $pod resume is for. It reads the current state of .cocoplus/ and produces a focused narrative:

You'll know in two minutes where you are and what to do next. The system maintained this state across every session while you were away. The hooks wrote it down. You just need to read it.

To see the full environment state again:


$cocoplus inspect

If it's been more than a few days, the Environment Inspector snapshot may be stale. A fresh scan ensures your context reflects the actual current state of your Snowflake environment — not the state it was in last week.

To see what CocoCupper learned last session:


$cup history 3

The last three sessions' findings. CocoCupper has been watching what happened each session and writing down what it noticed. By now it may have identified a recurring pattern in your SQL, a consistent error type, or a decision that keeps getting revisited. These are worth reading before you start building again.

Scenario 6: Handling a Safety Gate Trigger

The situation: You're in the Build phase. A stage in your pipeline tries to drop a table. The Safety Gate fires.

In strict mode: The SQL does not execute. The error is clear:


[Safety Gate — BLOCKED]
DROP TABLE ANALYTICS.CUSTOMER_FEATURES matched production schema pattern.
Operation blocked in strict mode. To proceed:
  - Verify this is an intentional and appropriate operation
  - Switch to normal mode: $safety normal
  - Then re-run the operation

This is not the system being obstructive. This is the system asking you to be intentional. If the drop is correct and expected, switch to normal mode, let it proceed, and consider switching back to strict when the operation completes.

In normal mode: The SQL runs, but you receive a warning in the session context:


[Safety Gate — WARNING]
TRUNCATE TABLE PROD_STAGING.TEMP_LOAD matches a production schema pattern.
This operation was executed. Review if this was intentional.

The warning is a record. If something downstream breaks, you have a log of what ran and when.

Configuring which schemas are protected:

The default protects schemas containing "PROD", "PRODUCTION", or "LIVE". If your project uses different naming conventions:


# In cocoplus.toml — [security] section
# Add your protected schema patterns to the protected_patterns array
[security]
protected_patterns = ["PROD", "PRODUCTION", "LIVE", "REGULATED"]

Run $cocoplus sync after editing cocoplus.toml to propagate the change to all generated artifacts. The Safety Gate reads from the synced configuration on every call.

When batch operations need a pre-flight review:

Before any CocoFlow stage that will run multiple destructive operations, the Safety Gate's soft layer presents a batch summary:


[Safety Gate — Soft Gate]
Stage "schema-rebuild" will execute:
  - DROP TABLE STAGING.OLD_CUSTOMER (3.2M rows)
  - DROP TABLE STAGING.OLD_ORDERS (8.7M rows)
  - CREATE TABLE ... (x2)

Confirm to proceed (yes/no):

You see exactly what's about to happen. You confirm or you don't. The system never runs a batch destructive operation silently.

Scenario 7: Exploring Before Committing — CocoSpark

The situation: You have a requirements brief but you're not sure of the best architectural approach. You want to think out loud before writing a spec that commits you to a direction.


$cocoplus spark schema design

CocoSpark activates for the topic "schema design." In divergent thinking mode, it generates at least three distinct approaches to your problem, articulates the trade-offs of each, identifies hidden assumptions in your framing, and raises questions you may not have thought to ask.

The output is saved to .cocoplus/spark-[timestamp].md and marked explicitly as exploration — not a plan, not a spec, not a commitment.

When you've finished exploring:


$cocoplus spark-off

You'll be asked if you want to carry any insights into spec.md. This is your decision. CocoSpark never modifies your lifecycle artifacts automatically. What goes forward is what you choose to take.

Running multiple spark sessions on different aspects:


$cocoplus spark data modeling approach

Then later:


$cocoplus spark cost optimization strategies

Each spark session generates its own timestamped file. You can reference them when writing your spec. They don't expire and they're never deleted — they're your exploration history.

Scenario 8: Building Institutional Memory — CocoGrove

The situation: You've completed a build and CocoCupper has flagged a pattern — a particular way of handling Snowflake pagination that worked consistently across several stages. You want to save this permanently.

First, review what CocoCupper found:


$cup history 1

You see the findings from the last session. Among them:


FINDING-047: Pattern "cursor-based pagination via ROWNUM + dense_rank()" used in stages 3, 5, and 7 with consistent success. Zero downstream errors. Potential candidate for promotion to CocoGrove.

To promote this finding to a permanent pattern:


$patterns promote FINDING-047

You'll be asked for a name, a brief description, context (when to apply), anti-context (when not to apply), and tags. After you confirm, the pattern is saved to .cocoplus/grove/patterns/ as a structured markdown file.

Browsing patterns by tag in future sessions:


$patterns view pagination

Returns all patterns tagged "pagination." Any agent invoked in a future session that reads from CocoGrove — during Build, Review, or a direct persona invocation — has access to this knowledge. It is no longer locked in your memory. It's in the system's.

A pattern is only valuable if it's accurate. If a promoted pattern turns out to have limitations you didn't notice at promotion time, you can update or annotate it directly in the .cocoplus/grove/patterns/ files. They're markdown. They're in git. They're yours to maintain.

Scenario 9: Large-Scale Builds with CocoFleet

The situation: Your data platform build has twelve independent components — several schemas, multiple semantic models, a set of Snowpark pipelines, and governance documentation. This is too large for a single CocoHarvest session.

This is when CocoFleet is the right tool. CocoHarvest runs within a single Coco session. CocoFleet spawns independent Coco processes at the OS level — each with its own full context window, each capable of handling a workstream too large for a subagent.

Initialize the fleet manifest:


$fleet init data-platform

This creates .cocoplus/fleet/data-platform-manifest.json as a template. You edit this file to define your instances — each with a task file path, persona assignment, output directory, and dependency list.

Run the fleet:


$fleet run .cocoplus/fleet/data-platform-manifest.json

CocoFleet resolves the dependency graph and spawns instances in dependency order. When an instance with no dependencies completes, its dependent instances start.

Monitor execution:


$fleet status fleet-001

Live view of all instances — status, runtime, checkpoint states. If any instance is failing:


$fleet logs instance-003

Streams the log file for that specific instance. You can diagnose, fix, and re-run individual instances without touching the rest of the fleet.

Stop the fleet:


$fleet stop fleet-001

Graceful shutdown — SIGTERM to running processes, waiting for clean exit, SIGKILL only for anything still running after 10 seconds. The state file is updated to reflect what was stopped and what state each instance was in.

CocoFleet vs CocoHarvest — the rule of thumb:

If your parallel workstreams fit comfortably in a single Coco session's context budget, use CocoHarvest — it's simpler and benefits from Coco's native hook system. If you're building something genuinely large, where individual workstreams themselves need a full context window, that's CocoFleet territory.

Don't use CocoFleet for small projects. The overhead of managing a fleet manifest is not justified when CocoHarvest handles it without configuration.

Scenario 10: Starting Faster with CocoRecipe

The situation: You're initializing a new project to build a Cortex Analyst semantic model over an existing schema. You've done this kind of work before and you know the standard stages. You don't want to write a CocoFlow pipeline definition from scratch.

First, browse what's available:


$recipe list

You'll see the standard library. The cortex-analyst-setup recipe describes exactly what you're doing: schema inspection → model draft → refinement → validation. It's parameterized — you'll supply the schema name and semantic model name, and the recipe does the rest.


$recipe use cortex-analyst-setup

CocoPlus prompts for the parameters this recipe needs: target_schema, semantic_model_name, warehouse. You provide them. A populated flow.json is generated in your .cocoplus/ directory with the full pipeline definition, stage assignments, checkpoint specifications, and prompt stubs already filled in for your specific context.

Before you proceed, inspect what was generated:


$flow view

The DAG opens in your browser. You see four stages in sequence, their dependencies, their persona assignments. If the structure looks right, close the browser and proceed. If you want to add a stage — say, a governance review by $dst between the model draft and refinement — you can edit flow.json directly. The recipe is a starting point, not a constraint.

When you're satisfied:


$cocoplus build

The pipeline executes. You saved the thirty minutes it would have taken to write flow.json and figure out the right stage sequence from first principles. The recipe embedded the hard-won experience of everyone who's run this pattern before.

Saving a successful pipeline as a recipe for future projects:

After a successful build, if your flow.json represents a pattern you'll want to reuse:


$recipe new

CocoPlus identifies the environment-specific values in your flow.json — schema names, model assignments, warehouse targets — and converts them to named parameters. You provide a recipe name and a brief description, and the template is saved to your CocoPlus profile folder. Every future project has access to it.

This is institutional memory at the pipeline level. Where CocoGrove stores prompt and SQL patterns, CocoRecipe stores execution architecture patterns. Together, they encode the accumulated engineering knowledge of your team into the tool that every team member uses.

Scenario 11: Locking Decisions Before the Plan — CocoDiscuss

The situation: You're about to build a significant AI function — a customer intent classifier that will be called by a production analytics pipeline. The spec is complete. You've been burned before by plans that made reasonable-seeming model choices and evaluation methodology assumptions without asking you. You want those decisions locked before the planning agent starts filling gaps.

Running the discuss session:


$discuss

The discuss wizard opens a structured dialogue tailored to your spec. It identifies that you're building an AI function and asks the implementation questions that matter: which Cortex model, what evaluation data and how many examples, what accuracy threshold, which warehouse, what governance requirements must pass before deployment, and what is explicitly out of scope.

Some questions are answered automatically. If your CocoContext has an approved models list with a single production-approved option, the wizard records that standard and skips the question. You see: "Model: Claude Haiku 4.5 (from approved-models.md — team standard)." You confirm.

For questions CocoContext doesn't answer, you respond directly. "Evaluation data: production sample, 500 rows from ANALYTICS.CUSTOMER_EVENTS, last 90 days." "Accuracy threshold: ≥88% on labeled evaluation set." Each answer is written to lifecycle/discuss.md.

The CocoSpec gate:

Before $cocoplus plan can run, the CocoSpec gate evaluates the combined spec.md and discuss.md. A Haiku subagent scores five dimensions: Value, Scope, Acceptance, Boundaries, Risk — 0 to 2 on each, maximum 10.

Your spec had no explicit error handling specification. Boundaries scored 1. Total: 9 out of 10. Gate passes — but the scoring output shows the named assumption: "UNCERTAIN: behavior when AI_COMPLETE returns null | ASSUMPTION: return default category 'UNKNOWN'." You add the error handling spec to spec.md. Boundaries scores 2. Gate passes cleanly.

What happens during planning:


$cocoplus plan

The planning agent reads discuss.md as a constraint document. It generates an execution plan that specifies exactly the model and evaluation methodology you locked. After generating the plan, the plan-checker validates every discuss decision against the plan. No Pre-Approval Conflicts. The plan proceeds to the approval gate.

The value: the planning agent made no silent choices. Every implementation decision in the plan can be traced to either the spec or the discuss document. When the build completes and SecondEye reviews it, the Decision Coverage Gate has a complete surface to check against.

Scenario 12: Navigating a Complex Function Ecosystem — CocoMap

The situation: Your Snowflake project now has eleven Cortex AI functions spread across four business domains. You're about to modify the shared preprocessing function that three classifiers depend on. Before committing, you want to know the full blast radius. Before the project got this large, you want to understand what you have.

Building the knowledge graph:


$map

Five analysis agents launch in parallel. Two minutes later — during which you've done nothing — the analysis completes. Your terminal shows:


CocoMap analysis complete.
Functions: 11 | Dependencies: 23 | Capabilities: 4 | Gaps: 2

Capabilities detected:
  customer_intent (3 functions)
  document_extraction (4 functions)
  sentiment_analysis (2 functions)
  churn_prediction (2 functions)

Gaps:
  ANALYTICS.EMAIL_CLASSIFIER — no evaluation baseline
  ANALYTICS.SEGMENT_PREDICTOR — depends on ANALYTICS.TEXT_NORMALIZER (undocumented)

Two pieces of information you didn't have before: a classifier running in production with no accuracy baseline, and a dependency chain through an undocumented function. Both would have been invisible without the map.

Checking the blast radius before your change:

You've staged your changes to TEXT_NORMALIZER. Before committing:


$map diff

Impact report:


Modified: ANALYTICS.TEXT_NORMALIZER
Downstream dependents (direct): ANALYTICS.SEGMENT_PREDICTOR
Downstream dependents (transitive): ANALYTICS.CHURN_SCORE_V2
Shared evaluation sets affected: eval_customer_segments (used by both)
Capability definitions changed: churn_prediction (vocabulary shift: "text normalization" → "preprocessing layer")

You weren't planning to affect the churn prediction capability. Now you know it will. You either scope the change more carefully or document the intended downstream effect. Either way, you're not discovering this in production.

Understanding a function you haven't touched in months:


$map explain ANALYTICS.CUSTOMER_INTENT_CLASSIFIER

Plain language: what it does, what it depends on, what depends on it, when it was last analyzed, which evaluation set governs it. Faster than reading four separate SQL files and a spec document.

Scenario 13: Managing Context Through a Long Build — CocoHealth

The situation: You're in the middle of a complex build — Prompt Studio optimization on a multi-model classifier, now in its eighth iteration cycle. CocoHealth fires its advisory.

The 60% advisory:

Mid-session, the next response begins with:


⚠️ Context is 60% full. Consider `$pod checkpoint` to preserve state before continuing.

You're not blocked. This is soft guidance. You're at a natural stopping point — the current prompt iteration just completed. You run it.


$pod checkpoint

Checkpoint written to lifecycle/checkpoint.md: current CocoBrew phase (Build), active Prompt Studio iteration ID, last five decisions, no pending must-fix items, no active CocoHarvest harvest.

"Checkpoint saved. Run $clear to reset context, then $pod resume to continue from this point."

You're not done with the session yet. You continue.

The 70% critical warning:

Four more tool calls. The critical threshold fires:


🔴 Context at 70% — reasoning quality may be affected.

Recovery recommendation: Commit partial + resume
Your state:
  Uncommitted changes: Y (6 files)
  Recent phase commits: Y
  Checkpoint: exists

Recommended next step: Commit current iteration artifacts, then $clear + $pod resume

The decision matrix evaluated your state and gave you one specific action. You don't have to reason about what to save — the system already did that reasoning. Commit the iteration artifacts. Run $clear. Run $pod resume.

Resuming in a fresh context:


$pod resume

The resume summary includes the checkpoint: which phase, which iteration, what decisions were made, what the immediate next action is. You're not rebuilding from scratch — you're continuing from a known point, with a context window that can reason clearly again.

The practical lesson: build the habit of running $pod checkpoint at natural session checkpoints — before long tool chains, before optimization loops, when the work has reached a coherent resting point. The checkpoint is not just for recovery from failure. It is for the deliberate recovery that CocoHealth recommends before the session degrades.

Scenario 14: Committing to the Outcome Before the Specification — CocoBloom

The situation: You're about to build an AI function that classifies customer support tickets by sentiment. You've done this kind of thing before. The impulse is to go straight to $spec. But the last three builds in this project have drifted — they started as one thing and shipped as a slightly different thing, and nobody is sure exactly when or why.

The working backwards discipline:


$bloom

Four questions. The bloom dialogue opens.

"Who benefits from this and what changes for them?" — A data analyst who currently waits overnight for a sentiment batch report will get results in under ten minutes.

"What is the core capability in one sentence?" — A Cortex LLM function that classifies customer support tickets into 12 sentiment categories with ≥88% accuracy on the production ticket distribution.

"What are the three constraints that bound this solution?" You name them: must run in the ANALYTICS schema, must cost ≤ 0.05 credits per classification, must not export PII data outside Snowflake.

"Write the press release paragraph." You write it. The agent gives you an example to start from, but the content is yours. One paragraph, as if the feature is already shipped and working.

The output commits to lifecycle/bloom.md. The commit message: feat(bloom): pre-commitment working backwards document.

When $spec runs:


$spec

The specification dialogue begins with bloom.md as its first context. Every question the spec wizard asks is anchored to what you committed. If the dialogue heads somewhere that would diverge — a different schema, a wider scope — the spec notices and asks you to confirm.

The bloom document stays in the project for the full lifecycle. At ship time, CocoWatch includes a one-line note: "Bloom commitment met." Or: "Bloom commitment partially diverged — see lifecycle/bloom.md." That sentence is worth reading before you merge.

Scenario 15: Getting Independent Perspectives on a Hard Decision — CocoKlatch

The situation: You're making an architecture decision that will constrain the project for the next several months. Should you implement this as a single Cortex LLM function or as a pipeline of three specialized functions? You have a preference. You want it challenged before you commit to it.

The roundtable:


$klatch "Should we implement the sentiment classifier as a single Cortex LLM function or a pipeline of three specialized functions?"

CocoKlatch prepares a structured brief from your question and spawns three subagents simultaneously. The Skeptic, the Optimist, and the Pragmatist each receive the same brief and nothing else — no knowledge of each other, no knowledge of what the others will say.

While they work, you see nothing. The agents are genuinely isolated. Each produces an independent analysis file.

When all three complete, the synthesis agent reads all three outputs:

The Skeptic found that a three-function pipeline introduces three evaluation surfaces instead of one, multiplying the accuracy risk without proportionate benefit given the task's relative uniformity.

The Optimist found that the three-function approach would allow independent fine-tuning per category cluster, potentially delivering higher ceiling accuracy and easier future maintenance.

The Pragmatist found that the timeline and the team's current evaluation infrastructure favor the single function — the pipeline approach is architecturally superior but requires evaluation tooling you don't yet have.

The synthesis: there is genuine disagreement. The single function is the better choice for this sprint; the pipeline approach should be recorded as a CocoSeed idea with trigger condition "when evaluation infrastructure supports multi-stage pipelines."

The decision path: You read the synthesis. You add the deferred idea:


$seed add "Refactor to three-function pipeline for independent fine-tuning" --trigger "when multi-stage evaluation pipeline is in place"

You proceed with the single function, informed rather than simply opinionated.

Scenario 16: Managing Large Artifacts Without Losing Information — CocoPull

The situation: You're running a CocoHarvest build with twelve parallel stages. Several stages produce large output files — schema analysis runs, evaluation result summaries, intermediate audit logs. By stage eight, some of those files have grown to 15,000 tokens. Loading them all into the stage nine agent's context would exhaust the context budget before the agent has written a single line.

The automatic distillation:

CocoHarvest checks each stage input's estimated token count before spawning. Any input over 8,000 tokens triggers an automatic pull check. For files that don't yet have a .pull.md counterpart, CocoHarvest runs $pull automatically. You see a brief note in the stage log: "Input compressed: evaluation-results.md → evaluation-results.pull.md (18,200 → 4,100 tokens, 77% reduction)."

The stage nine agent reads the pull file. Every accuracy threshold it needs is verbatim. Every schema name is verbatim. The narrative explanation of why the evaluation ran the way it did has been compressed to its conclusion. The agent has what it needs without the context pressure.

When you want to verify the compression:


$pull lifecycle/stage-006-schema-analysis.md --validate

A verification agent reads only the pull file and answers probe questions drawn from the source. You see the match rate: 94%. The pull file is reliable for this document type. Future pulls of schema analysis files can be trusted.

The practical habit: Run $pull --validate the first time you encounter each document type in a new project. Schema analyses, evaluation result sets, audit logs — they each have different information architectures. Once you've validated that a given type compresses faithfully, you can trust the automatic compression without re-checking.

Scenario 17: Closing the Quality Loop on an Artifact — CocoSentinel

The situation: You've built a Snowflake SQL classifier function. It passed the SecondEye spec review, CocoHarvest ran cleanly, the tests passed. Before you run $cocoplus review and $cocoplus ship, you want to evaluate the artifact itself — not the plan, but the output.

Running the gate:


$sentinel queries/sentiment_classifier.sql

CocoSentinel first runs Dimension G — the deterministic evidence pre-gate. It confirms the submission includes an execution record (your query results from the test phase), that the test cases have non-trivial expected outputs, that no success claims appear without attached evidence. Dimension G passes.

Seven dimension sub-agents spawn simultaneously. Twenty minutes later (most of the wait is the Sonnet-tier agents for correctness and performance), you see the synthesis:


CocoSentinel Result: CONDITIONAL
- A1: CONCERN (BLOCKING) — EXECUTE IMMEDIATE in line 34 uses string concatenation from WAREHOUSE_NAME parameter. Recommend IDENTIFIER($warehouse_name) binding.
- B: PASS
- C: CONCERN (ADVISORY) — join order puts smaller table on left. Recommend swap for large-scale execution.
- D: PASS
- E: CONCERN (ADVISORY) — two non-obvious regex patterns lack comments.
- F: PASS

You fix the A1 BLOCKING concern — IDENTIFIER binding. The advisory concerns you note for the next iteration.


$sentinel --approve --rationale "A1 resolved. C advisory accepted for current scale. E deferred to next review."

The SHA-bound approval is recorded. The artifact's SHA is computed and stored. If you modify the file, the approval voids automatically.

What CocoWisdom records: The BLOCKING A1 concern is written to wisdom/rejections.jsonl. On the next CocoSentinel invocation in this project — for any artifact — the A1 dimension agent will be primed with this rejection pattern. Your project has learned that EXECUTE IMMEDIATE construction is a recurring risk for this codebase.

Scenario 18: Understanding Your Project's Quality Patterns — CocoWisdom

The situation: Three months into a project, you've run SecondEye and CocoSentinel dozens of times. Before a sprint retrospective, you want to understand whether your quality patterns are improving and where the persistent gaps are.


$wisdom insights

A Haiku sub-agent reads the accumulated rejections.jsonl and writes an insights report to .cocoplus/wisdom/insights-2026-05-25.md. You share it in the retrospective:


Most Frequently Blocked Dimension: acceptance_criteria — 14 blocks (29% of all rejections)
Pattern: Specifications consistently omit numerical bounds for accuracy and performance thresholds.

Quality Trend: Improving — last 6 sessions had 0 rejections, down from 3.2 per session in March.

Dimension Health:
  acceptance_criteria  14 blocks  2 last 30 days  Improving
  security_posture      9 blocks  1 last 30 days  Stable
  null_handling         6 blocks  0 last 30 days  Resolved

The team's action: add an explicit numerical threshold checklist to the spec template. The next cycle of SecondEye invocations reflects the change — the acceptance_criteria dimension failures drop to zero over the following six sessions.

For searching prior decisions:


$wisdom search "PII masking"

Returns every rejection record that mentioned PII masking — with record IDs, dates, and evidence excerpts. You can trace the history of a recurring issue without reading through commit logs.

Scenario 19: Structured Code Review Before Ship — CocoReview

The situation: Your CocoSentinel evaluation returned APPROVED. Now you want an integrative review before making the Ship decision — not dimensional analysis, but a holistic look at whether the code does what it should and whether anything important was missed.


$cocoplus review queries/sentiment_classifier.sql

CocoReview runs pr-complexity.js first: complexity score 0.41, size bucket M, estimated 25-minute review. No risk flags. Proceeds to the four-phase review.

Phase 2 (high-level) surfaces an observation: the function's error handling path returns a generic error code rather than the specific code defined in the project's error taxonomy in cocoplus-context.md. This is a structural concern — better to surface it before line-by-line work.

Phase 3 (line-by-line) finds two additional items: a nested conditional three levels deep (nit — not blocking), and a reuse gap — a sanitization utility already in the CocoGrove pattern library covers exactly the pre-processing step that was implemented from scratch.

The verdict:


Verdict: COMMENT — can merge after addressing the error code alignment. 
Strengths [praise]: Clustering key alignment is correct and explicit. 
  The NULL handling on VARIANT fields is thorough.
Required Changes: Error code must match project taxonomy (blocking).
Suggestions: Nested conditional could be flattened (nit). Reuse existing sanitization utility (suggestion).

$cocoplus review --security when the context requires it:

If the function handles user-supplied inputs or PII-classified columns, you'd add the security flag. CocoReview loads the security review guide and the OWASP-aligned severity tiers. Critical findings block merge. In this case, the A1 BLOCKING concern that CocoSentinel already caught and fixed would have surfaced here too under security review — the two gates provide overlapping coverage from different angles.

Scenario 20: Grounding a Sprint Retrospective in Evidence — CocoOps

The situation: You're preparing for a sprint retrospective on a data pipeline project that's been running for six weeks. You want to bring data, not impressions.


$ops dora

CocoOps runs dora-metrics.js against Snowflake task execution history and git log. Six minutes later (the Snowflake query takes most of the time):


CocoOps DORA Report — customer-analytics — 2026-05-25

Pipeline Run Frequency:    2.8 / day   [High tier: 1/week–1/day]
Data Availability Lead:    3.1 hours   [High tier: <24 hours]
Failure Recovery Time:     72 minutes  [High tier: <1 day]
Data Quality Failure Rate: 18%         [Low tier: >15%]

Overall health: MEDIUM

Notable signals:
• Pipeline `sentiment_refresh_daily` accounts for 6 of 11 failures in the last 14 days
• 4 PRs modifying production pipelines had no corresponding test additions
• Lead time spike on 2026-05-14 (+340%) correlated with schema migration in commit a3f2b9c

The Data Quality Failure Rate is the discussion focus: 18% is in the Low tier. The narrative is precise — not "quality failures are high" but "four PRs modified production pipelines without test additions." That's an engineering practice question, not a capability question. The team adds a PR checklist.

Time-aware guidance during the day:


$ops suggest

At 9am on a Monday morning, CocoOps returns the overnight pipeline run status, any failed tasks since Friday's close, and the data freshness state across the three monitored schemas. No vague advice — specific pipeline names, failure timestamps, freshness deltas. The on-call team member has what they need before the standup.

A workflow is only a workflow when it outlasts the first deviation. The ones worth keeping are the ones that bend without breaking.