bloom

$bloom

Run a structured pre-spec working-backwards dialogue that captures the developer's commitment to the outcome before any specification is written. The bloom document anchors $spec, informs $discuss alignment checks, and is referenced at $ship by CocoWatch.

Preconditions

.cocoplus/ must be initialized (run $pod init first)

Arguments

--skip (optional): Waive the bloom step and suppress all bloom advisory messages in $spec
--resume (optional): Resume an incomplete bloom dialogue from .cocoplus/lifecycle/bloom-draft.json
--discard (optional): Delete an incomplete bloom draft after confirmation
--template <type> (optional): Show an example press-release pattern for ai-function, governance, analytics-pipeline, api-integration, or data-quality

Step-by-Step Behavior

`$bloom` — Four-Question Working Backwards Dialogue

Verify initialization: Check .cocoplus/ exists. If not, output: "CocoPlus not initialized. Run $pod init first." and exit.

Check existing bloom: If lifecycle/bloom.md already exists, prompt:

A bloom document already exists. Overwrite it? (The existing version will be preserved in git history.) [Y/N]

If developer answers N: exit without changes.

Open structured four-question dialogue — ask each question in sequence, waiting for the developer's full response before proceeding. After each accepted answer, persist progress to .cocoplus/lifecycle/bloom-draft.json with current_step, answered fields, and updated_at.

If --resume is provided, read bloom-draft.json, show progress such as 3/4 questions complete, and continue from the first unanswered question.

If --discard is provided, confirm before deleting bloom-draft.json. Do not delete a completed bloom.md.

Q1 — Beneficiary:
```
Who benefits from this, and what changes for them?
(Name the beneficiary and describe the specific before/after contrast.)
>
```
Minimum acceptable answer: one sentence naming a beneficiary and stating the change. If the response is too vague (e.g., "users benefit"), prompt once: "Can you be more specific — who exactly, and what specifically changes for them?"

Q2 — Core Capability:
```
What is the core capability in one sentence?
>
```
If the developer provides more than one sentence, prompt once: "Can you capture that in one sentence?" Accept the compressed version or the original if they confirm it is already one sentence.

Q3 — Constraints:
```
What are the three constraints that bound this solution?
(Examples: schema restrictions, cost limits, PII rules, performance requirements)
Constraint 1: >
Constraint 2: >
Constraint 3: >
```
If fewer than three are provided, ask for the remaining ones by number. If more than three are provided, ask the developer to prioritize to exactly three.

Q4 — Press Release:
```
Write the press release paragraph.
Write as if the feature is already shipped and working: who can now do what,
how fast, with what quality, at what cost.

Example: "Snowflake data teams can now classify customer support tickets automatically
using a fine-tuned Cortex function. The classifier processes 10,000 tickets per hour
at under 5 credits, with 91% accuracy on labeled test data. Teams that previously
waited overnight for sentiment reports now receive them in real-time."

Write your paragraph below (the agent will not generate this for you):
>
```
If --template <type> is provided, show one example matching that project type before Q4. Templates are examples only; the developer still writes the actual paragraph. Do not generate the press release paragraph from the developer's Q1–Q3 answers. The developer writes it themselves. If the developer asks the agent to write it, respond: "The press release must be written by you — it is the commitment artifact. Try writing one sentence at a time: who benefits, what they can do now, and how well it works."

Assemble and write lifecycle/bloom.md:

---
bloom_date: [ISO8601 timestamp]
status: complete
---

## Beneficiary
[Answer to Q1]

## Core Capability
[Answer to Q2]

## Constraints
- [Constraint 1]
- [Constraint 2]
- [Constraint 3]

## Press Release
[Answer to Q4]

Create git commit: feat(bloom): pre-commitment working backwards document

After successful write, remove bloom-draft.json if it exists.

Output confirmation:

✓ Bloom document created.

lifecycle/bloom.md committed.
Run $spec — the specification dialogue will use this as its anchor.

`$bloom --skip` — Waive the Bloom Step

Verify initialization: Check .cocoplus/ exists. If not, output error and exit.
Write waiver flag: Update .cocoplus/lifecycle/meta.json to include "bloom_waived": true. If meta.json does not exist, create it with { "bloom_waived": true }.

Output:

Bloom waived. Run $spec — no advisory message will appear.

Effect: When $spec subsequently runs and finds "bloom_waived": true in meta.json, it does not display the bloom advisory note and does not attempt to read any bloom document.

Integration with Downstream Phases

$spec: If lifecycle/bloom.md exists, reads it first as anchoring context. Begins dialogue with: "I've read your bloom document. The core capability is: [core sentence from bloom]. I'll use that as the anchor for this specification."
$discuss: Includes bloom.md in its pre-plan validation — checks that the final plan still serves the beneficiary and constraint set declared in the bloom. Divergence surfaces as a Concern (not a Block).
$ship: If bloom document exists, CocoWatch includes a one-line alignment note: "Bloom commitment [met / partially diverged] — see lifecycle/bloom.md."

Error Cases

.cocoplus/ not initialized: Output: "CocoPlus not initialized. Run $pod init first."
bloom.md exists and developer declines overwrite: Exit without changes
Cannot write bloom.md: Output filesystem error
Cannot write meta.json (for --skip): Output filesystem error
Cannot write bloom-draft.json: Output filesystem error and stop before asking the next question

Exit Criteria

This skill is complete when ONE of the following is true:

lifecycle/bloom.md is written with all four sections populated and committed to git
lifecycle/meta.json contains "bloom_waived": true (for --skip path)
Incomplete sessions can resume from bloom-draft.json

Anti-Rationalization

Do NOT:

Generate the press release paragraph on the developer's behalf — Q4 is always developer-written
Require more or fewer than exactly three constraints in Q3 — the number is fixed by design
Enforce bloom before $spec — it is advisory only ($spec shows a one-line prompt, not a block)
Modify spec.md, plan.md, or any other lifecycle artifact — bloom only writes lifecycle/bloom.md
Create a git commit until all four questions are answered and the developer has confirmed the content
Use templates as generated commitments — examples guide the developer, they do not replace the developer-written paragraph