goal-progress-bar ยท diff
git:20261024.21f0bb2 to git:20261028.97a5db1
36 added, 1 removed. Audit A to A.
---
name: goal-progress-bar
description: Use to show weighted progress for a multi-step task and update it from recorded evidence.
---
# 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](references/evidence-and-scope.md). 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. End with
+ 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`:
```bash
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:
```bash
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:
```html
<!-- 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.