Goal progress bar

Use this skill for work with three or more steps that runs long enough for someone to ask how close it is to done. Skip it for a quick answer or one-step task.

Each task gets one tracker file. The script renders the current percentage, bar, and row status at each checkpoint. Never type or adjust those values by hand.

Define what done means

Agree the deliverables and acceptance evidence before choosing weights. The percentage measures completion of that scope. It is not elapsed time, an ETA, confidence, or permission to release. Include review, deployment, live checks, or requester decisions only when the task actually requires them.

For a long-running or shared goal, read evidence and scope. Keep evidence and owners beside the tracker without adding fields to its row format.

Set up a tracker

1. Write <goal>-progress.json in your task folder. The file is a JSON list of [name, weight, fraction] rows.
2. Use one row for each deliverable or proof that moves the goal. Examples include code, review, release, live verification, and requester approval. Use names the requester understands.
3. Use weight 1 for a small row and 2 for a large or critical row. Choose weights before reporting progress. End with the rows that prove the work is complete in real use.
4. Add a fourth field to a row that cannot move: [name, weight, fraction, "blocked"]. Remove the field when work resumes.

Render the tracker

Run the script from the task folder. Replace <skill-root> with the folder that contains this SKILL.md:

python3 <skill-root>/scripts/progress.py <goal>-progress.json "<Goal name>"

On Windows, use py -3 or your installed Python 3 command instead of python3. Quote paths containing spaces. The same script accepts UTF-8 trackers with or without a byte-order mark, including files written by Windows PowerShell.

Add --chat for emoji codes suited to chat systems that render common emoji shortcodes:

python3 <skill-root>/scripts/progress.py <goal>-progress.json "<Goal name>" --chat

The chat bar uses green squares for complete work, one yellow square for partial work, and white squares for the rest. Each row starts with a green, yellow, white, or red status circle. Send the rendered text without a code block if the destination converts emoji codes.

Update at each checkpoint

A checkpoint is a finished step, such as a reviewed change, release, live check, or answer from the requester.

• Back up the tracker before each edit, for example: cp <goal>-progress.json <goal>-progress.json.bak-<date>-<time>.
• Set a code row to 1.0 only when its defined work is complete.
• Set a proof row to 1.0 only with real evidence, such as a receipt, live read, or requester answer. Never round up to done before the proof exists.
• Add a row when the goal grows. Never delete a row to raise the percentage.
• A newly discovered requirement can lower the percentage. Explain the scope change. If work is explicitly removed from scope, retain the old tracker and record the decision before calculating the revised baseline.
• Preserve earned progress while a row is blocked. Record the blocker and next owner in the evidence notes. A row at 1.0 cannot also be marked blocked.
• Reopen a proof row when its supporting build, artifact, or external state changes. Old evidence does not prove the current result.

Input and completion checks

Names must be nonempty single-line text. Weights must be positive finite numbers; fractions must be finite numbers from 0 to 1. A fourth field must be exactly "blocked", for unfinished work only. An empty tracker renders 0%. Missing, malformed, or invalid trackers exit 2 without printing progress.

The renderer reserves 100% and a fully complete bar for rows whose fractions are all 1. It checks the numbers, not their evidence. Verify every acceptance condition before setting those fractions. Never invent approval or a live readback to finish the bar.

Share the result

• Paste the full script output without changes. Never type a percentage or bar by hand.
• Share it when work starts, at meaningful checkpoints, and when work ends. Do not post it again when nothing changed.
• When the destination supports message editing, update the first progress message in place and post a new message only at large milestones.
• In an issue or ledger, place the current output between these markers:

<!-- progress:start -->
<!-- progress:end -->

A finished task can replace the block with one dated 100% completion line. The next task then owns the live progress block.