Skip to content

dimagi-internal/ace / skills/connect-opp-modify

connect-opp-modify

Verified

Change a live Connect opportunity: verification flags, payment units, dates, budget, visit caps or the Learn pass mark, with a before-read and read-back. Use when asked to extend or reconfigure a live opp. Needs the opp id.

FileKindSize
SKILL.mdskill md7.9 KB
---
name: connect-opp-modify
description: >
  Change a live Connect opportunity: verification flags, payment units, dates, budget, visit caps or
  the Learn pass mark, with a before-read and read-back. Use when asked to extend or reconfigure a
  live opp. Needs the opp id.
---

# Modify a live Connect opportunity

Changes configuration on an opportunity that already exists, whether or not ACE built it. Each
change reads the current value, writes it, and reads it back. Playwright-backed writes report the
POST status, not the saved state, so only the read-back counts.

Platform facts: [`connect-api.md` § Changing a live opportunity](../../playbook/integrations/connect-api.md#changing-a-live-opportunity)
and § Data model gotchas. This skill is the procedure.

## Inputs

| Parameter | Used for | Resolver |
|---|---|---|
| `opportunity_id` | the opportunity UUID | explicit arg; default: run_state `phases.connect-setup.products.connect.opportunity.id`; else the program context doc's Scope |
| `program_org` | the org whose URL serves every opportunity operation: the **program's** org, not the holding org (`connect-api.md` § PM→NM org-URL matrix) | explicit arg; default: run_state `products.connect.pm_org_slug`; else the org in the program's recorded URL |
| `program_id` | needed only for the Learn passing score | explicit arg; default: `opp.yaml.connect.program.id`; else the context doc |
| `changes` | the requested change(s): any of `verification_flags`, `add_payment_units`, `end_date` / `name` / `short_description` / `description` / `active`, `total_budget`, `learn_passing_score` | explicit arg |

No `run_state.yaml` is needed.

## Products

- A change record with each field's before, requested and read-back values:
  - inside a run, `<N>-<phase>/connect-opp-modify_<YYYYMMDD-HHMM>.md`;
  - on a program project, a dated line in the context doc's Decisions.

## What this skill cannot do

| Requested | Why not | Say instead |
|---|---|---|
| Change or delete a payment unit (amount, caps, deliver units) | No atom exists | Do it in the Connect UI, or a new opportunity on a fresh Deliver release |
| Change the holding org | `target_organization_slug` is create-time only; `connect_update_opportunity` has no org field (ace#2919) | A new opportunity, which is a build, not a change |
| Delete the opportunity | No atom exists | Deactivate it (`active: false`) or delete it in the Connect UI |
| Bind a payment unit to a deliver unit another opportunity in the same holding org already holds | ace#573 | A fresh Deliver release |

Refuse these up front, with the reason, before any write.

## Process

1. **Confirm the approval.** These are writes to a live partner object. The caller at level 0 must
   already have shown the before and after values and got approval
   (`partner-on-connect-program § Changing a live program`). A subagent cannot ask the human; with
   no recorded approval, return the proposal and stop.
2. **Read the before state** at `program_org`:
   - `connect_get_opportunity`;
   - `connect_list_payment_units` and `connect_list_deliver_units`;
   - `connect_get_verification_flags`: the persisted `form_field_rules`, the per-deliver-unit
     duration floors and the submission window. It is read-only (ace#3161), so the before-read
     never goes through `connect_set_verification_flags`. An explicit `--form-field-rules`
     overrides it. Read it even when `changes` has no `verification_flags`: a new payment unit
     on a deliver unit that already carries rules changes what those rules gate;
   - for a passing-score change, `connect_get_learn_passing_score` (needs `program_id`).

   A missing opportunity at that org means the wrong org. Re-resolve it; never try the other org
   blind.
3. **Refuse what can't be done.** Check `changes` against § What this skill cannot do.
4. **Name the side effects in the proposal before writing:**
   - **Learn passing score:** shared by every opportunity in the holding org wired to the same
     HQ Learn app (ace#1350). List those opportunities with `connect_list_opportunities`.
     Changing the score changes the gate for all of them. Workers already past Learn are
     unaffected, because completion is one-way.
   - **New payment unit:** needs an unbound deliver unit. List the deliver units and check which
     are already referenced by `connect_list_payment_units`.
   - **Budget:** pass `total_budget` to `connect_create_payment_units`, so the server enforces
     funds for at least one worker (ace#729).
   - **`short_description` and slug:** both are truncated at 50 characters without warning.
     Refuse anything longer.
5. **Write, one change at a time**, each followed by its read-back. The payload rules for the
   first two live in one place, `connect-opp-setup` § Operations on an existing opportunity;
   follow them there rather than from memory:
   - **Verification flags:** `connect_set_verification_flags`, per `connect-opp-setup` Step 5
     (JSONPath `question_path` read from the released CCZ, the stored option value, the deliver
     unit's `server_id`, names of 25 characters or fewer, the refused dead flags). Its response
     carries `form_field_rules_saved` and the persisted rules. A deliver-unit move or a duration
     floor that did not persist is a typed error, not a success.
   - **Add payment units:** `connect_create_payment_units`, an atomic batch, per
     `connect-opp-setup` Step 6 (whole-currency integers, never cents; a non-empty
     `required_deliver_units` of `server_id`s; `total_budget` passed; the create response, not
     the listing, is the read-back).
   - **Dates, name, description, active:** `connect_update_opportunity`. Use it to deactivate
     only; activate with `connect_activate_opportunity`, which carries the activation
     preconditions.
   - **Learn passing score:** `connect_set_learn_passing_score`. Keep its
     `previous_passing_score` in the record. To diagnose a read-back that disagrees, use
     `connect-opp-setup` Step 4's `passing_score` check (`classifyPassingScoreReadback`).
6. **Read back and compare.** Run step 2's reads again and diff them against the requested values.
   Any mismatch is a failed change: report it. Retry only once, and only when the cause is
   understood.
7. **Record.** Write before, requested and read-back values to the record named in § Products.

## MCP Tools Used

- ace-connect: `connect_get_opportunity`, `connect_list_opportunities`, `connect_list_deliver_units`, `connect_list_payment_units`, `connect_get_verification_flags`, `connect_set_verification_flags`, `connect_create_payment_units`, `connect_update_opportunity`, `connect_activate_opportunity`, `connect_get_learn_passing_score`, `connect_set_learn_passing_score`

## Existing objects

- **Deliver units are shared** within a holding org on the same released Deliver app (ace#573). A
  new payment unit needs an unbound deliver unit. Step 4 checks for one; with none, refuse.
- **The Learn `passing_score` lives on the shared `CommCareApp` row** (ace#1350). Step 4 names
  every affected opportunity before any write.
- **The holding org is create-time only** (ace#2919). Refused in step 3.
- **There is no payment-unit update or delete atom.** Refused in step 3.

## Mode Behavior

- **Auto:** with approval recorded in the dispatch, writes and reads back each change; halts on the
  first mismatch.
- **Review:** presents the step 4 proposal (including every other opportunity a shared change
  touches) and waits.

## Dry-Run Behavior

When `--dry-run` is active, run steps 2–4 and write the proposal. Make no writes.

## Change Log

| Date | Change | Author |
|------|--------|--------|
| 2026-10-18 | Step 5 points at `connect-opp-setup` § Operations on an existing opportunity for the flag, payment-unit and passing-score mechanics, so they are written down once (#3148 batch 3) | ACE |
| 2026-10-18 | Initial version: change a live opportunity, with explicit "cannot" rows and shared-state warnings (audit item 6) | ACE (build-vs-maintain audit) |
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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall