dimagi-internal/ace / skills/decisions-render
decisions-render
VerifiedInternal /ace:run step — Render a per-run decisions.yaml into a prose Google Doc at one stable URL per run.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 7.2 KB |
SKILL.md
View on GitHub---
name: decisions-render
description: >
Internal /ace:run step — Render a per-run decisions.yaml into a prose Google Doc at one stable
URL per run.
user-invocable: false
disable-model-invocation: false
---
# Decisions Render
Read `decisions.yaml` from a run folder, render it as a prose Google Doc, and
write the result to `decisions.gdoc` at one stable URL.
## Inputs
Pipeline-only: renders a run's `decisions.yaml`, which exists only in a run.
| Source | Artifact | Used for |
|---|---|---|
| Per-run state | `ACE/<opp-name>/runs/<run-id>/decisions.yaml` | the structured log to render |
## Products
- `ACE/<opp-name>/runs/<run-id>/decisions.gdoc` — prose Google Doc rendering at one stable URL. Find-or-update semantics; existing content is cleared and replaced on every invocation. Each row renders an `AI-default:` line and, when the row is overridden, an `Override:` line immediately below it. The status line is plain text (`Status: applied` or `Status: overridden`).
## Terminology
Every string this skill puts in front of a reader follows
[`skills/_terminology.md`](../_terminology.md): **`Connect`, never `CommCare Connect`**, and
**US spelling, always** — program, enrollment, enroll, organization, behavior, center; never
programme, enrolment, organisation (owner, 2026-10-20: *"everything should be US spelling"*,
ace#3232). Identifiers (case properties, slugs, ids, config keys) keep their spelling.
## Process
1. **Resolve the run folder file ID** for `ACE/<opp-name>/runs/<run-id>/`.
Use `drive_list_folder` from the opp folder to find the run folder.
1.5. **Enrich the log first — `decisions_enrich` (REQUIRED, schema v6).** The
decisions log is the run's review artifact (the build memo is retired), and
the parts of it with a right answer are computed, not left to the producers:
```
mcp__plugin_ace_ace-decisions__decisions_enrich
{ runFolderId: "<run-folder file ID from step 1>" }
```
It reads `decisions.yaml` + `run_state.yaml` from the folder and stamps
rule `scope`/`enforcement`, `audience: internal` on harness rows, folds
cross-skill duplicates, and marks `review_ask: recommended-confirmation` on
every `PROPOSED` program parameter the build configured, every
machine-translated language, every enforcement gap, every `OPEN` row and
every open residual a person must decide (`docs/decisions-contract.md §
What earns a review_ask`). Idempotent; writes only on change. Carry its
`reviewAsks` list into the pause summary's `Decisions Log:` line ("N to
confirm before launch").
**Plain-language gate.** `report.plainLanguageGate.verdict: fail` is a
**FAIL** for this step, not a warning: list every `findings[]` entry as
`<id>.<field>: <finding>` grouped by `skill` (the producer that owes the
rewrite — `skills/_decisions-review-fields.md`), and carry the count into
the pause summary. It does not halt the render (the Doc is still the
reviewer's way in), but the same check blocks release
(`assessDecisionsPlainLanguage`), so a failing run cannot reach an outside
reviewer. Contract: `docs/decisions-contract.md § Plain-language gate`.
(`missingPlain` / `jargon` remain as flat views of the same findings.)
2. **Render via the `render_decisions_log` atom** (the canonical, single-call
path). Pass the run-folder file ID; the atom reads `decisions.yaml` from it,
renders the prose log via `lib/decisions-renderer.ts`, and find-or-updates
`decisions.gdoc` in the same folder — read + render + clear + batchUpdate all
happen server-side, so you never relay the generated Docs API JSON yourself:
```
mcp__plugin_ace_ace-gdrive__render_decisions_log
{ runFolderFileId: "<run-folder file ID from step 1>" }
```
Returns `{ gdocId, reused, requestCount, webViewLink }`. Each row renders an
`AI-default:` line, an `Override:` line when the row is overridden, and a
plain `Status: applied | overridden` line (see § Products for the exact
shape). The schema is validated server-side (`lib/decisions-schema.ts §
parseDecisionsYaml`); a malformed row throws with its dot-path.
- **Do NOT** hand-render the rows through `drive_create_doc_from_markdown`
or hand-relay `renderDecisionsLog` output through `docs_batch_update` —
that was the ~65KB-per-phase manual relay this atom replaces (jjackson/ace#574).
- `scripts/decisions-render.ts` (`runDecisionsRender`) is the library the
atom wraps; its `import.meta.url === ...` CLI branch is still intentionally
unwired (it needs a live Drive client). Don't shell out to the script.
3. **Confirm the gdoc URL** from the atom's `webViewLink` field. The orchestrator captures this URL for the pause summary's `Decisions Log:` line.
## Failure modes
- **decisions.yaml is missing**: the script throws with the run folder ID; the orchestrator's Phase Write-Back Verifier should have already created an empty decisions.yaml before this skill runs. If it didn't, the skill halts and surfaces the missing-file error to the operator.
- **Schema-invalid YAML**: the script throws with the dot-path of the offending field. The originating skill (whichever phase wrote the bad row) gets a hard fail; orchestrator surfaces it in the pause summary's BLOCKER list.
- **Docs API rate limit**: rare — the renderer makes one batch update per phase. Retry once after 30s; halt with actionable error if it fails again.
## MCP Tools Used
- Google Drive: `drive_list_folder` (step 1, resolve run folder), `render_decisions_log` (step 2, the single-call render)
- ace-decisions: `decisions_enrich` (step 1.5, the deterministic v6 review fields)
## Mode Behavior
- **Auto:** Run, no human pause. Stdout includes the gdoc URL for downstream skills.
- **Review:** Same as Auto — the renderer is deterministic, no human review of the rendering itself.
## Change Log
| Date | Change | Author |
|------|--------|--------|
| 2026-05-08 | Initial skill — pairs with `lib/decisions-renderer.ts` and `scripts/decisions-render.ts`. Renders decisions.yaml as a prose Google Doc; idempotent; runs at end of every phase. | ACE team (decisions-log PR #2) |
| 2026-05-31 | Canonical path is now the `render_decisions_log` MCP atom (wraps `runDecisionsRender` server-side) — one call with the run-folder file ID instead of hand-relaying ~65KB of `docs_batch_update` JSON per phase (jjackson/ace#574). | ACE team |
| 2026-09-06 | **Stop routing concerns to a gate brief that does not exist (dimagi-internal/ace#1884).** 0.13.116 removed the per-skill gate-brief file class and the ace#1880 sweep removed the remaining `*.md` PATHS, but prose directives naming the gate brief as a DESTINATION survived in 15 files — a concern "surfaced in the gate brief" is surfaced nowhere. Repointed at the verdict YAML's `auto_surfaced` block, which is what the orchestrator actually renders the pause summary from. Gated by the new destination check in `test/skills/gate-brief-removal-complete.test.ts`. | ACE team |
| 2026-10-03 | **Step 1.5: `decisions_enrich` before the render (schema v6).** The decisions log replaced the build memo as the review artifact; the enrichment computes rule scope/enforcement, harness `audience`, cross-skill dedupe and every derived `review_ask`, and the Doc now opens with "To confirm before launch". Contract: `docs/decisions-contract.md`. | ACE team |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |