Helper Files — Soapbox working-file pattern
Every deliverable-producing skill classifies its outputs into exactly two tiers, nothing in
between:
| Tier |
What |
Treatment |
Folder |
| Working / checklist |
ONE growing "helper" HTML per engagement + the verifier findings.md ledger. Absorbs all intermediate and gate material. |
Utilitarian — plain, terse, legible. Never "designed." |
Helper Files |
| Design-forward |
Exactly two client deliverables: the Report and the Delivery-Meeting Slides. |
Polished, brand-quality. Rendered only at their gate. |
Reports |
The verbose per-phase/per-gate HTML renders of the past do not exist here — they collapse into
checklist sections of the one helper file. Human gates are reviewed as the relevant checklist
section of the helper, never as a polished artifact.
The helper file
Identity (one growing file — never create a second)
- Folder:
Helper Files
- Filename:
[ISO start date] - Helper Files - [Deliverable Type].html
[ISO start date] = the engagement/analysis start date, captured once and fixed
forever (NOT the save date — a changing date recreates clutter). Store it in state
(state.helper.start_date, state.helper.filename) at engagement start and reuse verbatim
on every later save.[Deliverable Type] = Decarb Plan | Portfolio Analysis | Rehab Analysis | (skill's own).- Example:
2026-07-04 - Helper Files - Decarb Plan.html
- Save with
save_file using that exact name + folder. The runtime upserts by
(asset, name, folder) — reusing the identical name overwrites in place, so there is always
exactly one helper file. Never vary the name (no p1-…, no -v2, no asset suffix).
It is a rendered VIEW of the state file (no drift)
- The engagement state file (JSON) is the machine source of truth. The helper is its
human-readable projection.
- At every phase checkpoint, regenerate the WHOLE helper from current state and re-save it
under the fixed name. "Grows and adapts" = re-render from state. Never hand-edit the helper
so it diverges from state — if a value is in the helper, it came from state.
Structure (fill the skeleton in references/skeleton.html)
Top to bottom (the skeleton ships all of this — you populate it):
- Header badge — bold
INTERNAL WORKING FILE — NOT THE DELIVERABLE; deliverable type, asset/
portfolio, engagement start date, current phase, last-updated timestamp.
- Source-of-Truth panel — every key input as a row: value · source · provenance tier
(
measured > audit > modeled > estimate) · 🔒 if adjudicated/locked.
- Open Questions / pending adjudications — unresolved items + who owns each.
- Adjudication log — decision · locked value · date (append-only).
- Per-phase / per-gate checklist sections — one collapsible
<details> per workflow phase,
each a checklist with a status marker (✓ done / ○ in progress / ⚠ blocked) + the minimal
working detail. The phase list is supplied by the calling deliverable skill (see contract).
Styling: single self-contained HTML file, inline CSS, no external assets, utilitarian and legible.
Deliberately not brand-polished — polish is reserved for the Report and Slides.
Lifecycle
- Create at engagement start: capture fixed start date + filename into state; render the
skeleton with the Source-of-Truth panel seeded from kickoff.
- Update at every phase checkpoint: regenerate from state,
save_file under the fixed name.
- Gate review: point the user at the relevant checklist section of the helper — not a render.
- Never gate on the helper — gates read state; the helper is a working aid.
Contract for a deliverable skill using this pattern
A deliverable skill (decarb-plan, portfolio-analysis, rehab-analysis, …) must:
- At engagement start, set
state.helper.start_date (fixed) and state.helper.filename.
- Supply its phase/gate checklist list (the
<details> sections) and the Source-of-Truth
field set relevant to that deliverable.
- Regenerate +
save_file the helper (fixed name, folder Helper Files) at every checkpoint.
- Keep the two design-forward deliverables (Report, Slides) separate, in
Reports, gate-only.
- Do not produce standalone verbose intermediate/gate HTML — put that material in the helper
as checklist sections.
Notes
- The verifier plugin's
findings.md ledger also lives in Helper Files (working-tier material).
- This is doctrine + a skeleton, not a tool. No platform/runtime change is needed —
save_file
already provides upsert-by-name behavior.
1---2name: helper-files3description: The Soapbox working-file pattern shared by every deliverable-producing skill (Decarb Plan, Portfolio Analysis, Rehab Analysis, RSRA, …). Maintain exactly ONE growing, self-updating internal "helper" HTML per engagement — a utilitarian working companion (source-of-truth dashboard, open questions, adjudication log, per-phase/per-gate checklists) that absorbs all intermediate and gate material. It is NOT the deliverable: only the Report and the Delivery-Meeting Slides get the design-forward treatment, and only at their gate. Human gates are reviewed as checklist sections of the helper. Read this skill (by path) from any deliverable skill before creating or updating working artifacts. Triggers on: "helper file", "working file", "gate artifact", "scratchpad", "checklist", "source of truth doc", "where do I save this", "intermediate artifact", "working companion".4---56# Helper Files — Soapbox working-file pattern78Every deliverable-producing skill classifies its outputs into **exactly two tiers, nothing in9between**:1011| Tier | What | Treatment | Folder |12|---|---|---|---|13| **Working / checklist** | ONE growing "helper" HTML per engagement **+** the verifier `findings.md` ledger. Absorbs all intermediate **and gate** material. | **Utilitarian** — plain, terse, legible. Never "designed." | `Helper Files` |14| **Design-forward** | Exactly two client deliverables: the **Report** and the **Delivery-Meeting Slides**. | Polished, brand-quality. Rendered **only at their gate**. | `Reports` |1516The verbose per-phase/per-gate HTML renders of the past do **not** exist here — they collapse into17checklist sections of the one helper file. **Human gates are reviewed as the relevant checklist18section of the helper**, never as a polished artifact.1920## The helper file2122### Identity (one growing file — never create a second)23- **Folder:** `Helper Files`24- **Filename:** `[ISO start date] - Helper Files - [Deliverable Type].html`25 - `[ISO start date]` = the engagement/analysis **start date**, captured **once** and **fixed26 forever** (NOT the save date — a changing date recreates clutter). Store it in state27 (`state.helper.start_date`, `state.helper.filename`) at engagement start and reuse verbatim28 on every later save.29 - `[Deliverable Type]` = `Decarb Plan` | `Portfolio Analysis` | `Rehab Analysis` | (skill's own).30 - Example: `2026-07-04 - Helper Files - Decarb Plan.html`31- **Save with `save_file`** using that exact `name` + `folder`. The runtime upserts by32 (asset, name, folder) — reusing the identical name **overwrites in place**, so there is always33 exactly one helper file. Never vary the name (no `p1-…`, no `-v2`, no asset suffix).3435### It is a rendered VIEW of the state file (no drift)36- The engagement **state file (JSON) is the machine source of truth.** The helper is its37 human-readable projection.38- At **every phase checkpoint**, regenerate the WHOLE helper from current state and re-save it39 under the fixed name. "Grows and adapts" = re-render from state. **Never** hand-edit the helper40 so it diverges from state — if a value is in the helper, it came from state.4142### Structure (fill the skeleton in `references/skeleton.html`)43Top to bottom (the skeleton ships all of this — you populate it):441. **Header badge** — bold `INTERNAL WORKING FILE — NOT THE DELIVERABLE`; deliverable type, asset/45 portfolio, engagement start date, current phase, last-updated timestamp.462. **Source-of-Truth panel** — every key input as a row: value · source · provenance tier47 (`measured > audit > modeled > estimate`) · 🔒 if adjudicated/locked.483. **Open Questions / pending adjudications** — unresolved items + who owns each.494. **Adjudication log** — decision · locked value · date (append-only).505. **Per-phase / per-gate checklist sections** — one collapsible `<details>` per workflow phase,51 each a checklist with a status marker (`✓ done` / `○ in progress` / `⚠ blocked`) + the minimal52 working detail. **The phase list is supplied by the calling deliverable skill** (see contract).5354Styling: single self-contained HTML file, inline CSS, no external assets, utilitarian and legible.55Deliberately **not** brand-polished — polish is reserved for the Report and Slides.5657### Lifecycle58- **Create** at engagement start: capture fixed start date + filename into state; render the59 skeleton with the Source-of-Truth panel seeded from kickoff.60- **Update** at every phase checkpoint: regenerate from state, `save_file` under the fixed name.61- **Gate review**: point the user at the relevant checklist section of the helper — not a render.62- **Never gate on the helper** — gates read state; the helper is a working aid.6364## Contract for a deliverable skill using this pattern65A deliverable skill (decarb-plan, portfolio-analysis, rehab-analysis, …) must:661. At engagement start, set `state.helper.start_date` (fixed) and `state.helper.filename`.672. Supply its **phase/gate checklist list** (the `<details>` sections) and the **Source-of-Truth68 field set** relevant to that deliverable.693. Regenerate + `save_file` the helper (fixed name, folder `Helper Files`) at every checkpoint.704. Keep the two design-forward deliverables (Report, Slides) separate, in `Reports`, gate-only.715. Do **not** produce standalone verbose intermediate/gate HTML — put that material in the helper72 as checklist sections.7374## Notes75- The verifier plugin's `findings.md` ledger also lives in `Helper Files` (working-tier material).76- This is doctrine + a skeleton, not a tool. No platform/runtime change is needed — `save_file`77 already provides upsert-by-name behavior.
soapboxbuild