Skip to content

Complete Example: Accurate Render Stages and Progress

This example shows the same change moving through the Prompt + Skill + CLI process: “Show users accurate render stages and progress while their presentation video is being rendered.” IDs and URLs are illustrative.

1. Change intake in Linear

Create Product Main change issue ANU-310 with this description:

User outcome
When I submit a presentation video, I can see the render stage, useful progress,
and failure information so I know the job is active and what is happening.

Known constraints
- Web, Python, and Unity currently expose different lifecycle detail.
- Do not invent progress where a subsystem cannot measure it.
- Existing jobs and completed videos must remain readable.
- The Web app is the only user-facing module.

Priority
High

2. Product Main Codex App task

Open Product Main and send:

$anuva-development:linear-plan-change ANU-310

Skills invoked

  1. linear-plan-change reads and normalizes the issue.
  2. anuva-plan-product-change reads product context, applies the Plan Product Change prompt, and creates docs.
  3. anuva-preview-docs ensures the live documentation and returns URLs.

CLI calls before approval

anuva context show --json
anuva linear issue get ANU-310 --json
anuva docs ensure --repository anuva-main-video-creator --confirm
anuva docs validate-indexes --repository anuva-main-video-creator
anuva docs ensure --repository anuva-main-video-creator --confirm
anuva docs wait --repository anuva-main-video-creator \
  --since <pre-edit-timestamp> \
  --file docs/changes/2026-07-14-render-stage-progress/index.md \
  --file docs/changes/2026-07-14-render-stage-progress/ChangeBrief.md \
  --file docs/changes/2026-07-14-render-stage-progress/RepositoryImpact.md \
  --file docs/changes/2026-07-14-render-stage-progress/ImplementationIssues.md \
  --file docs/changes/2026-07-14-render-stage-progress/Progress.md

Product contract produced

The plan establishes one versioned render-progress event:

{
  "schemaVersion": 1,
  "jobId": "job_123",
  "sequence": 42,
  "status": "running",
  "stage": "rendering",
  "stageLabel": "Rendering presentation",
  "stageProgress": { "completed": 420, "total": 900, "unit": "frames" },
  "overallPercent": 61,
  "message": "Rendering frame 420 of 900",
  "occurredAt": "2026-07-14T10:20:30Z",
  "failure": null
}

Canonical stages:

Stage User label Accurate progress source
queued Waiting to render Queue position when available; no fabricated percent
preparing_assets Preparing presentation assets Python asset checklist
starting_renderer Starting video renderer Python Unity-process lifecycle
loading_scene Loading virtual studio Unity scene/load milestones
rendering Rendering presentation Unity completed/total frames
encoding Encoding video Unity or encoder completed/total frames/segments
uploading Uploading completed video Python bytes uploaded/total bytes
completed Video ready Terminal state, 100%
failed Render failed Terminal state with safe error code/message and retryability
canceled Render canceled Terminal state with cancellation source

Rules include monotonically increasing sequence; idempotent duplicate handling; no stage regression unless a new retry attempt is identified; optional progress when total work is unknown; safe user messages separated from diagnostic details; and compatibility mapping for legacy job states. overallPercent is emitted only from the agreed weighting calculation when its component measurement is known.

Repository issue drafts

Proposed issue Repository Scope Dependency
ANU-311 Unity Emit scene, render-frame, encoding, terminal, and failure progress using the approved contract boundary None after contract approval
ANU-312 Python Map Unity events, persist/order progress, expose current state, upload progress, compatibility, monitoring ANU-311 for full integration
ANU-313 CMS Store/consume current progress, show accessible stage UI, reconnect/retry behavior, and Playwright coverage ANU-312 for live integration

Codex approval response

The product plan defines ten canonical stages and forbids fabricated percentages.
It splits delivery into Unity ANU-311, Python ANU-312, and CMS ANU-313, sequenced
Unity → Python → CMS for integration.

Review:
- https://main1.girishd.com/changes/2026-07-14-render-stage-progress/
- https://main1.girishd.com/changes/2026-07-14-render-stage-progress/ChangeBrief/
- https://main1.girishd.com/changes/2026-07-14-render-stage-progress/RepositoryImpact/
- https://main1.girishd.com/changes/2026-07-14-render-stage-progress/ImplementationIssues/
- https://main1.girishd.com/changes/2026-07-14-render-stage-progress/Progress/

After approval I will run:
anuva linear change create-implementation-issues
docs/changes/2026-07-14-render-stage-progress/implementation-issues.json --confirm

After the user says “Approved”, Codex runs the command, records actual IDs/URLs, and waits for the updated docs preview.

3. Unity implementation task

Open a Codex App task in anuva-unity-video-creator:

$anuva-development:linear-list-ready-issues
$anuva-development:linear-implement-issue ANU-311

The skills read the issue, start a codex/anu-311-render-progress-events branch, create and preview ImplementationPlan.md, and pause if requested. Unity work adds the event emission and deterministic tests/manual render evidence appropriate to the project.

Representative CLI calls:

anuva linear issue list-ready --repository current --json
anuva linear issue get ANU-311 --json
anuva work start ANU-311 --confirm
anuva docs ensure --repository current --confirm
anuva docs validate-indexes --repository current
anuva docs ensure --repository current --confirm
anuva docs wait --repository current \
  --since <pre-edit-timestamp> \
  --file docs/changes/2026-07-14-render-stage-progress/index.md \
  --file docs/changes/2026-07-14-render-stage-progress/ImplementationPlan.md
anuva pr create ANU-311 --draft --confirm

When ready:

$anuva-development:anuva-review-and-complete-pr ANU-311

Codex inspects checks/evidence, returns the Unity docs URL, pauses, then merges and marks ANU-311 Done after approval.

4. Python implementation task

After ANU-311 is complete, open anuva-python-server:

$anuva-development:linear-list-ready-issues
$anuva-development:linear-implement-issue ANU-312

Python implements event validation and ordering, retry-attempt handling, progress persistence, upload byte progress, user-safe errors, legacy-state mapping, API or push delivery to CMS, and monitoring. Tests cover duplicate/out-of-order events, Unity restart, upload failure, unknown totals, retries, and terminal states.

The CLI/skill sequence matches Unity, with Python verification commands supplied by the repository skill. Complete with:

$anuva-development:anuva-review-and-complete-pr ANU-312

5. CMS implementation task

Open anuvax-cms:

$anuva-development:linear-list-ready-issues
$anuva-development:linear-implement-issue ANU-313

The anuva-implement-issue skill loads the Implement CMS Issue prompt. The plan covers:

  • render-job schema/API consumption and legacy state mapping;
  • accessible stage label and progress display;
  • indeterminate progress when no truthful total exists;
  • reconnect, refresh, retry-attempt, failed, canceled, and completed behavior;
  • no stale event overwriting a newer sequence; and
  • Playwright tests for queued, stage transitions, refresh/reconnect, failure, and completion using deterministic event fixtures plus one Python integration path.

Representative commands:

anuva work start ANU-313 --confirm
anuva docs ensure --repository current --confirm
anuva docs validate-indexes --repository current
anuva docs ensure --repository current --confirm
anuva docs wait --repository current \
  --since <pre-edit-timestamp> \
  --file docs/changes/2026-07-14-render-stage-progress/index.md \
  --file docs/changes/2026-07-14-render-stage-progress/ImplementationPlan.md
anuva pr create ANU-313 --draft --confirm
anuva pr inspect ANU-313 --json
anuva pr checks ANU-313 --json

At the implementation pause, Codex returns a URL such as:

https://web1.girishd.com/changes/2026-07-14-render-stage-progress/
https://web1.girishd.com/changes/2026-07-14-render-stage-progress/ImplementationPlan/

Finish with:

$anuva-development:anuva-review-and-complete-pr ANU-313

After approval, the skill runs anuva pr ready ANU-313 --confirm, then anuva pr merge ANU-313 --report C:\absolute\path\CompletionReport.md --confirm. The merge operation records evidence and completes Linear; retry it unchanged if GitHub merged but the Linear update partially failed.

6. Product completion task

Return to Product Main after all three implementation issues are Done:

$anuva-development:anuva-review-product-change ANU-310

Codex refreshes read-only state, verifies end-to-end evidence, updates Progress.md, creates CompletionReview.md, previews both pages, and pauses before completing the parent change. If accepted, it runs:

anuva linear change complete ANU-310 \
  --review docs/changes/2026-07-14-render-stage-progress/CompletionReview.md \
  --confirm

It then records the receipt and refreshed change state.

The completion review confirms that a real job traverses Unity → Python → CMS, the UI never invents progress, terminal/failure states are correct, legacy jobs remain readable, Playwright passes, and all repository docs and PRs are linked.