Skip to content

armelhbobdad/bmad-module-ultracode-goal / skills/ultracode-goal

ultracode-goal

Flagged

Runs a BMAD Epic autonomously to a machine-checked Definition-of-Done. Use when the user requests to 'run an epic autonomously', 'execute this epic', 'ultracode goal', or 'autonomously deliver the epic'.

FileKindSize
SKILL.mdskill md15.9 KB
assets/module-help.csvother2.1 KB
assets/module-setup.mdmarkdown5.9 KB
assets/module.yamlconfig1.9 KB
assets/ucg-awareness/bmad-architecture.tomlconfig2.5 KB
assets/ucg-awareness/bmad-create-epics-and-stories.tomlconfig3.3 KB
assets/ucg-awareness/bmad-prd.tomlconfig2.1 KB
assets/ucg-awareness/bmad-testarch-nfr.tomlconfig1.8 KB
assets/ucg-awareness/bmad-testarch-test-design.tomlconfig3.1 KB
assets/ucg-awareness/shaping-decision.mdmarkdown6.8 KB
assets/ucg-awareness/ucg-create-story.tomlconfig3.3 KB
customize.tomlconfig9.8 KB
references/define-done.mdmarkdown15.4 KB
references/execute.mdmarkdown120.0 KB
references/finalize.mdmarkdown39.3 KB
references/gate.mdmarkdown143.7 KB
references/health-check.mdmarkdown27.0 KB
references/ingest-and-scope.mdmarkdown28.2 KB
references/preflight.mdmarkdown83.6 KB
scripts/carry_build_cache.pyscript18.6 KB
scripts/claim_check.pyscript36.3 KB
scripts/drive_epic.pyexecutablescript64.2 KB
scripts/formalize_check.pyscript87.5 KB
scripts/gate_eval.pyexecutablescript67.8 KB
scripts/gate_trail.pyexecutablescript52.6 KB
scripts/headless_envelope.pyscript12.6 KB
scripts/health_check_fp.pyscript66.5 KB
scripts/hooks/budget_stop.pyexecutablescript18.7 KB
scripts/hooks/guard_pretooluse.pyexecutablescript180.1 KB
scripts/lib/mem_common.pyscript64.6 KB
scripts/link_worktree_deps.pyscript28.6 KB
scripts/mem_observation.pyscript35.5 KB
scripts/mem_recall.pyscript19.9 KB
scripts/merge_config.pyexecutablescript13.8 KB
scripts/merge_customization.pyscript18.7 KB
scripts/merge_help_csv.pyscript9.5 KB
scripts/moved_ac_check.pyscript10.0 KB
scripts/mutate_check.pyscript64.4 KB
scripts/operator_owed.pyscript18.6 KB
scripts/preflight_check.pyscript115.2 KB
scripts/probe_servers.pyscript38.7 KB
scripts/red_ids.pyscript14.0 KB
scripts/status_render.pyscript26.0 KB
scripts/story_sizing.pyexecutablescript11.7 KB
scripts/tests/bench_ucg_formalize.mdmarkdown7.3 KB
scripts/tests/fixtures/claude_mem_real_payload.jsonconfig3.4 KB
scripts/tests/fixtures/engine-6.12/README.mdmarkdown957 B
scripts/tests/fixtures/engine-6.12/config_utils.pyscript4.1 KB
scripts/tests/fixtures/engine-6.12/resolve_customization.pyexecutablescript5.1 KB
scripts/tests/fixtures/engine/README.mdmarkdown1.0 KB
scripts/tests/fixtures/engine/resolve_customization.pyexecutablescript8.0 KB
scripts/tests/fixtures/execute_pre_verification_axes.mdmarkdown29.1 KB
scripts/tests/fixtures/execute_resume_clause_no_baseline.mdmarkdown215 B
scripts/tests/fixtures/execute_run_status_preedit.mdmarkdown1.2 KB
scripts/tests/fixtures/execute_spine_end_no_escalation_fire.mdmarkdown194 B
scripts/tests/fixtures/execute_step0_baseline_no_sha.mdmarkdown1.0 KB
scripts/tests/fixtures/execute_ticker_line.mdmarkdown332 B
scripts/tests/fixtures/finalize_epic_complete_hook_no_escalation.mdmarkdown579 B
scripts/tests/fixtures/finalize_headless_output_hand_composed.mdmarkdown1.2 KB
scripts/tests/fixtures/finalize_no_graphify_section.mdmarkdown19.4 KB
scripts/tests/fixtures/floor/all_clean/impl-artifacts/7-1-clean.mdmarkdown477 B
scripts/tests/fixtures/floor/all_clean/impl-artifacts/sprint-status.yamlconfig88 B
scripts/tests/fixtures/floor/all_clean/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/all_clean/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/all_clean/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/all_clean/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/invented_threshold/impl-artifacts/61-1-threshold.mdmarkdown564 B
scripts/tests/fixtures/floor/invented_threshold/impl-artifacts/sprint-status.yamlconfig94 B
scripts/tests/fixtures/floor/invented_threshold/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/invented_threshold/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/invented_threshold/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/invented_threshold/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/invented_threshold_unknown/impl-artifacts/61-1-threshold.mdmarkdown644 B
scripts/tests/fixtures/floor/invented_threshold_unknown/impl-artifacts/sprint-status.yamlconfig94 B
scripts/tests/fixtures/floor/invented_threshold_unknown/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/invented_threshold_unknown/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/invented_threshold_unknown/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/invented_threshold_unknown/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/leaked_tea/impl-artifacts/9-1-leak.mdmarkdown475 B
scripts/tests/fixtures/floor/leaked_tea/impl-artifacts/sprint-status.yamlconfig87 B
scripts/tests/fixtures/floor/leaked_tea/impl-artifacts/test-design-9-1.mdmarkdown291 B
scripts/tests/fixtures/floor/leaked_tea/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/leaked_tea/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/leaked_tea/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/leaked_tea/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/leaked_tea_clean/impl-artifacts/9-1-leak.mdmarkdown475 B
scripts/tests/fixtures/floor/leaked_tea_clean/impl-artifacts/sprint-status.yamlconfig87 B
scripts/tests/fixtures/floor/leaked_tea_clean/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/leaked_tea_clean/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/leaked_tea_clean/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/leaked_tea_clean/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/leaked_tea_clean/tea/traceability/test-design-9-1.mdmarkdown296 B
scripts/tests/fixtures/floor/orphaned_index/impl-artifacts/10-1-orphan.mdmarkdown513 B
scripts/tests/fixtures/floor/orphaned_index/impl-artifacts/sprint-status.yamlconfig91 B
scripts/tests/fixtures/floor/orphaned_index/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/orphaned_index/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/orphaned_index/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/orphaned_index/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/orphaned_index_resolved/impl-artifacts/10-1-orphan.mdmarkdown508 B
scripts/tests/fixtures/floor/orphaned_index_resolved/impl-artifacts/10-2-helper.mdmarkdown479 B
scripts/tests/fixtures/floor/orphaned_index_resolved/impl-artifacts/sprint-status.yamlconfig120 B
scripts/tests/fixtures/floor/orphaned_index_resolved/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/orphaned_index_resolved/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/orphaned_index_resolved/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/orphaned_index_resolved/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/sourced_threshold/impl-artifacts/61-1-threshold.mdmarkdown609 B
scripts/tests/fixtures/floor/sourced_threshold/impl-artifacts/sprint-status.yamlconfig94 B
scripts/tests/fixtures/floor/sourced_threshold/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/sourced_threshold/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/sourced_threshold/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/sourced_threshold/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/unclassified_signal/impl-artifacts/12-1-signal.mdmarkdown552 B
scripts/tests/fixtures/floor/unclassified_signal/impl-artifacts/sprint-status.yamlconfig91 B
scripts/tests/fixtures/floor/unclassified_signal/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/unclassified_signal/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/unclassified_signal/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/unclassified_signal/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/unclassified_signal_removed/impl-artifacts/12-1-signal.mdmarkdown483 B
scripts/tests/fixtures/floor/unclassified_signal_removed/impl-artifacts/sprint-status.yamlconfig91 B
scripts/tests/fixtures/floor/unclassified_signal_removed/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/unclassified_signal_removed/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/unclassified_signal_removed/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/unclassified_signal_removed/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/vacuous_ac/impl-artifacts/8-1-vacuous.mdmarkdown435 B
scripts/tests/fixtures/floor/vacuous_ac/impl-artifacts/sprint-status.yamlconfig90 B
scripts/tests/fixtures/floor/vacuous_ac/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/vacuous_ac/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/vacuous_ac/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/vacuous_ac/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/floor/vacuous_ac_sound/impl-artifacts/8-1-vacuous.mdmarkdown482 B
scripts/tests/fixtures/floor/vacuous_ac_sound/impl-artifacts/sprint-status.yamlconfig90 B
scripts/tests/fixtures/floor/vacuous_ac_sound/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/floor/vacuous_ac_sound/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/floor/vacuous_ac_sound/tea/config.yamlconfig104 B
scripts/tests/fixtures/floor/vacuous_ac_sound/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/formalize/epic-clean-control/LABEL.mdmarkdown751 B
scripts/tests/fixtures/formalize/epic-clean-control/impl-artifacts/7-1-clean.mdmarkdown477 B
scripts/tests/fixtures/formalize/epic-clean-control/impl-artifacts/sprint-status.yamlconfig88 B
scripts/tests/fixtures/formalize/epic-clean-control/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/formalize/epic-clean-control/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/formalize/epic-clean-control/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/epic-clean-control/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/formalize/epic-judgment-seed/LABEL.mdmarkdown1.1 KB
scripts/tests/fixtures/formalize/epic-judgment-seed/impl-artifacts/61-1-threshold.mdmarkdown564 B
scripts/tests/fixtures/formalize/epic-judgment-seed/impl-artifacts/sprint-status.yamlconfig94 B
scripts/tests/fixtures/formalize/epic-judgment-seed/planning-artifacts/architecture-fixture.mdmarkdown236 B
scripts/tests/fixtures/formalize/epic-judgment-seed/planning-artifacts/prd-fixture.mdmarkdown225 B
scripts/tests/fixtures/formalize/epic-judgment-seed/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/epic-judgment-seed/tea/traceability/e2e-trace-summary.jsonconfig48 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/impl-artifacts/6-1-experience.mdmarkdown1.3 KB
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/impl-artifacts/sprint-status.yamlconfig93 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/planning-artifacts/architecture-fixture.mdmarkdown93 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/planning-artifacts/prd-fixture.mdmarkdown84 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/low_ratio_zero_gap_epic/tea/traceability/.keepother32 B
scripts/tests/fixtures/formalize/ready_epic/impl-artifacts/1-1-kernel.mdmarkdown848 B
scripts/tests/fixtures/formalize/ready_epic/impl-artifacts/1-2-floor.mdmarkdown538 B
scripts/tests/fixtures/formalize/ready_epic/impl-artifacts/sprint-status.yamlconfig110 B
scripts/tests/fixtures/formalize/ready_epic/planning-artifacts/architecture-fixture.mdmarkdown218 B
scripts/tests/fixtures/formalize/ready_epic/planning-artifacts/prd-fixture.mdmarkdown207 B
scripts/tests/fixtures/formalize/ready_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/ready_epic/tea/traceability/e2e-trace-summary.jsonconfig49 B
scripts/tests/fixtures/formalize/remediable_epic/impl-artifacts/2-1-thin.mdmarkdown202 B
scripts/tests/fixtures/formalize/remediable_epic/impl-artifacts/sprint-status.yamlconfig87 B
scripts/tests/fixtures/formalize/remediable_epic/planning-artifacts/architecture-fixture.mdmarkdown94 B
scripts/tests/fixtures/formalize/remediable_epic/planning-artifacts/prd-fixture.mdmarkdown85 B
scripts/tests/fixtures/formalize/remediable_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/remediable_epic/tea/traceability/.keepother32 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/impl-artifacts/4-1-signal.mdmarkdown546 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/impl-artifacts/sprint-status.yamlconfig89 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/planning-artifacts/architecture-fixture.mdmarkdown103 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/planning-artifacts/prd-fixture.mdmarkdown94 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/unclassified_signal_epic/tea/traceability/.keepother32 B
scripts/tests/fixtures/formalize/unreadable_epic/impl-artifacts/3-1-broken.mdbinary28 B
scripts/tests/fixtures/formalize/unreadable_epic/impl-artifacts/sprint-status.yamlconfig89 B
scripts/tests/fixtures/formalize/unreadable_epic/tea/config.yamlconfig85 B
scripts/tests/fixtures/formalize/unreadable_epic/tea/traceability/.keepother14 B
scripts/tests/fixtures/formalize/wrong_root_epic/impl-artifacts/5-1-place.mdmarkdown420 B
scripts/tests/fixtures/formalize/wrong_root_epic/impl-artifacts/prd-fixture.mdmarkdown226 B
scripts/tests/fixtures/formalize/wrong_root_epic/impl-artifacts/sprint-status.yamlconfig88 B
scripts/tests/fixtures/formalize/wrong_root_epic/planning-artifacts/architecture-fixture.mdmarkdown187 B
scripts/tests/fixtures/formalize/wrong_root_epic/tea/config.yamlconfig104 B
scripts/tests/fixtures/formalize/wrong_root_epic/tea/traceability/.keepother32 B
scripts/tests/fixtures/gate_run_the_gate_no_ticker.mdmarkdown5.7 KB
scripts/tests/fixtures/gate_trail/light/decision-log.mdmarkdown341 B
scripts/tests/fixtures/gate_trail/light/impl-artifacts/.baseline-2-4other41 B
scripts/tests/fixtures/gate_trail/light/impl-artifacts/.baseline-2-6other41 B
scripts/tests/fixtures/gate_trail/light/test-artifacts/traceability/gate-decision-2-4.jsonconfig751 B
scripts/tests/fixtures/gate_trail/light/test-artifacts/traceability/gate-decision-2-6.jsonconfig755 B
scripts/tests/fixtures/gate_trail/light/test-artifacts/traceability/trace-2-4.mdmarkdown1.4 KB
scripts/tests/fixtures/gate_trail/light/test-artifacts/traceability/trace-2-6.mdmarkdown1.3 KB
scripts/tests/fixtures/gate_trail/production/decision-log.mdmarkdown783 B
scripts/tests/fixtures/gate_trail/production/impl-artifacts/.baseline-7-1other41 B
scripts/tests/fixtures/gate_trail/production/impl-artifacts/.baseline-7-2other41 B
scripts/tests/fixtures/gate_trail/production/impl-artifacts/.baseline-7-3other41 B
scripts/tests/fixtures/gate_trail/production/test-artifacts/atdd-checklist-7-1.mdmarkdown509 B
scripts/tests/fixtures/gate_trail/production/test-artifacts/atdd-checklist-7-2.mdmarkdown300 B
scripts/tests/fixtures/gate_trail/production/test-artifacts/traceability/gate-decision-7-1.jsonconfig648 B
scripts/tests/fixtures/gate_trail/production/test-artifacts/traceability/gate-decision-7-2.jsonconfig679 B

references/health-check.md

View on GitHub
# Health Check: Workflow Self-Improvement

Reflect on the ultracode-goal run that just completed and capture the friction, bugs and gaps you hit in this module's workflow instructions (not the user's code) as structured findings, for its maintainers to fix. A direct run, the one an operator asks for against a run folder, reports from the `friction:` entries of that folder's `.decision-log.md` alone (§2), since nothing of that run is in context, and routes by its run mode like any run (§4).

## Anti-fabrication rules

- Report only friction that was **actually hit**: by you this run, or by the run that logged a `friction:` entry §2 reads. A fabricated issue is worse than none, because it pollutes the maintainers' queue. Reporting zero issues is the healthy, expected outcome for a well-designed workflow.
- If you are unsure whether something was a real issue or your own confusion, do not report it.

## 1. Enabled gate

If `{workflow.health_check_repo}` is empty, the check is off: append `health-check: disabled` to `.decision-log.md` and return, touching nothing but that marker line. Otherwise, in an attended run, tell the user in `{communication_language}` that you are running a quick self-improvement check that closes at once if nothing rough came up.

**The marker.** Every exit of this check appends exactly one `health-check: <outcome>` line to `.decision-log.md`, in place of any other line about how it ended: `disabled` (above), `clean` (§2), `discarded` (§4a **[N]**) or `done` with its counts (§6). §2 reads only the `friction:` entries after the last such line, so the next health check reports again the entries of a check that ended without one, at an unanswered gate say.

**Appending to the log.** The marker, and every line this file says to log, is appended to `.decision-log.md` with Write or Edit, never a Bash heredoc. Once the log is too large to Read affordably, do not Read it: Write the line to a new file beside the log, `<log folder>/dlog-slice-stage7-<n>.md`, where `<log folder>` is the run folder's full path and `<n>` is one past the highest number a `dlog-slice-stage7-*.md` there already carries, then append it in one Bash call, `cat "<log folder>/dlog-slice-stage7-<n>.md" >> "<log folder>/.decision-log.md"`, and keep the slice.

**A defect in this check.** A defect in this file's instructions, or in a script or command it runs, that bites while the check runs §3 to §6 is a finding of the stage `health-check` (§4). Until §6 appends its marker, fingerprint and draft it (§3) and queue it as §4 says. Take at most one per check: append any further one, and one that bites once the marker is in, as a `friction: health-check.md "<section heading>": <what bit>` line after the marker, which the next health check reads.

## 2. Find the findings

First read the `friction:` entries no health check has reported yet: search `.decision-log.md` with the Grep tool, with line numbers, for the regex `^\s*([-*]\s+)?(friction:|health-check: (disabled|clean|discarded|done)\b)`, which finds an entry or a marker only at the start of its line (after a list bullet at most), never one quoted inside another entry. Take the `friction:` entries after the last marker (all of them when there is none). Use the Grep tool, not a shell grep: it reads a log too large to Read, and a shell grep is outside the headless allowlist. Each entry names the stage file and the section heading where an instruction was unclear, contradictory or silent on the case in hand. Drop an entry whose section heading or instruction the current stage file no longer carries: an upgrade may sit between the run that logged it and this check. Then find each point where a stage instruction you were following was wrong or contradictory (`bug`), worked but left you guessing or going back and forth (`friction`), or was silent on a case you hit (`gap`): in a direct run from those entries alone, in any other from them, the rest of the log and what is still in context. A finding's `stage` is whichever of `ingest-and-scope`, `preflight`, `define-done`, `execute`, `gate`, `finalize` was being followed when it bit, or `health-check` when the instruction is this file's own or belongs to a script or command it runs. If there is none, append `health-check: clean` (§1), display "Health Check: clean run. No workflow issues to report." in an attended run, and return.

## 3. Fingerprint and draft each finding

Every finding, whatever its route, gets its fingerprints and its issue body on disk before anyone reviews it: a gate left unanswered leaves the drafts in the run folder.

**Name the section and the defect.** The section is the heading of the innermost section of `references/{stage}.md` whose instruction bit, copied exactly as that file writes it, numbering included. A bold run-in label (`**Foo.**`) is no heading: take the heading that encloses it. A defect in an instruction of `SKILL.md` or of a script takes the heading of the stage-file section that was running when it bit, or the file's H1 when none fits; one that bit before any stage file was running (On Activation, the resume routing) takes the stage `ingest-and-scope` and that file's H1. The defect name is the thing the fix would change, in the stage reference's or the script's own words: a script by its file name, a subcommand, a function, a flag, a field, a verdict, a rule's term or a section's concept. Pick the most specific name the fix would edit, so two different defects in one section get two fingerprints while two reports of one defect that name the same thing get one. When the defect is a missing rule, there is no name to copy yet: name the case the rule should cover in two to four of the stage reference's own words, the noun the rule would be about, then what makes the case distinct (a missing rule for a story whose acceptance criteria moved, in a section whose rule covers a re-gated story, is `story moved criteria`). Never use a path, a line number, a severity or words from this run's own story: whoever reports the same defect next must reach the same name from the source alone. Never use the section's own subject alone either: every defect in the section shares it.

**Compute the fingerprints and the title with the script.** Give the finding a one-line short description of the defect for its issue title. Write the two names and the description with the Write tool to `hc-name-{n}.json` in this run's folder (beside `.decision-log.md`), `{n}` being the finding's number, as the JSON object `{"section_heading": "<the heading>", "defect_name": "<the name>", "short_description": "<the description>"}` with each value JSON-escaped, so no quote in a name meets the shell. Then run, `<run folder>` being that folder's full path:

```
uv run {skill-root}/scripts/health_check_fp.py fingerprint --severity {severity} --stage {stage} \
  --stdin < "<run folder>/hc-name-{n}.json"
```

→ `{"fp", "legacy_fp", "tuple", "section_slug", "defect_key", "title", "regression_title", "body_header"}`. The script turns the heading into the section slug and the name into the defect key, one to four lower-case ASCII words joined by hyphens (`gate_eval.py` gives `gate-eval`, `operator's own evidence` gives `operators-own-evidence`). `{legacy_fp}` is the section fingerprint, which every defect of one severity in one section shares, so a match on it is only ever a possible match. `{title}` is the issue title and `{regression_title}` the same with `REGRESSION: ` before the description: use them exactly as printed, wherever this finding's title appears. A null `title` or `body_header` means the description was missing from the file: write it there and run the call again, and never write `null` into a title or a draft. A value that breaks its rule makes the call exit 1 with a JSON `error` naming the rule (the description may hold no backtick, `$`, double quote, backslash, `!`, tab, line break or other character that is not printable, since the title goes on a command line, and may not make `regression_title` longer than 256 characters). When it names the severity, the stage, the name or the description, fix that value and run the call once more; when it refuses the heading, take the heading that encloses that one (the file's H1 at the top) and run the call once more. Never loop: when that second call fails too, or a call prints no JSON at all (uv or Python could not run), log it, naming the finding, and drop that finding. Two findings that get one `{fp}` are one defect: merge them into one finding before drafting.

**Write the draft.** Write each finding's issue body with the Write tool to `hc-body-{fp}.md` in the run folder, opening with the call's `body_header` exactly as printed. Every route uses that file as it stands: the gate shows it, `gh` posts it with `--body-file`, and the queue copies it. After the gate the draft changes only by a regression's opening line (§5a step 1) or an **[N]** re-key at the dedup gate (§5a-i). Never put a body on a command line: a body often quotes paths, and while a recall latch is still present (Finalize's unlatch failed, so the report names the latch path) the guard denies any Bash command that names the latch; quotes, backticks and `$` in a body also break shell quoting. The guard reads the paths a Write names, not what it writes, so a body file passes. Before writing `hc-name-{n}.json` or `hc-body-{fp}.md`, Read a file of that name an earlier invocation left, since the Write tool refuses to overwrite a file it has not read. If either Write fails, log its error, naming the finding, and drop that finding: there is no text to show, post or queue. When no finding survives this step, go straight to §6, with no gate.

**Writing rules** (a maintainer triages the issue without this run in the room):

- **One issue per finding.** Two independent problems → two issues.
- **Respect length budgets.** Finding, Expected, Actual, Impact, Suggested Fix are each one sentence. Evidence is 2-5 bullets, not prose.
- **Quote, do not paraphrase.** In Evidence, cite the exact `file:line` with the quoted text in quotes.
- **Cite only this module's files.** Evidence quotes `SKILL.md`, the stage references and the scripts under `skills/ultracode-goal/`, never the user's project code, the Epic's content or a secret.
- **Never narrate the session.** The reader wants the defect, not the story. If a sentence starts with "During my run…", delete it.

**Issue body**: the `body_header`, then these `## ` headings in order, as the issue template
writes them: `## Finding`, `## Expected`, `## Actual`, `## Evidence`, `## Impact`,
`## Suggested Fix`, and `## Environment`, a table carrying: Date (ISO), OS, AI Editor, Model,
Profile (`production | light`), Run mode (`attended | headless`), and Module Version.

**Module Version comes from the script:**

```
uv run {skill-root}/scripts/health_check_fp.py version --project-root {project-root}
```

→ `{"version", "source"}`. Write `version` into the Environment table; write `N/A` when it is `null`, or when the call fails or prints no JSON.

## 4. Route by run mode

**Split the repository with the script**, once, before the gate and every `gh` call:

```
uv run {skill-root}/scripts/health_check_fp.py repo --repo "{workflow.health_check_repo}"
```

→ `{"repo", "host", "owner_repo", "host_flag", "is_default"}`. `{host}` is the host the value names, as `gh` reads it (`github.com` for `OWNER/REPO`), `{owner_repo}` the repository without its host, and `{host_flag}` the flag that names that host to `gh`, empty for an `OWNER/REPO` value: use each exactly as printed, and never write a host or a flag of your own. If the call fails or prints no JSON (no `uv` or script, or a value that is not `[HOST/]OWNER/REPO`), log its error: the repository stays **unsplit**, so every finding routed to live-submit goes to the local queue (§5c) with the reason "Posting these to GitHub failed." and no call of §5a runs for it.

**A finding about the health check itself.** A finding whose stage is `health-check` is never posted. Every route that submits or queues (**[Y]**, **[A]**, **[Q]** and headless) writes it to the local queue (§5c) with the reason "Found in the health check's own instructions; review it before submitting.", which replaces any reason its route would give; **[N]** discards it with the rest. Filing it would have the run's last step post a report about itself, and a defect in that filing would call for another.

### 4a. Attended routing (HALT gate)

Show every finding: for each one, its `{title}` (§3), the path of its draft and the draft's full text. Say that when the seen-cache check finds the defect was fixed before, one line naming that fix opens the body, and a confirmed regression's title gains `REGRESSION: ` before its short description (§5a step 1). Say too that a finding about the health check itself (stage `health-check`) is queued, never posted, whatever you choose but **[N]** (§4). When every finding's stage is `health-check`, ask instead "Queue these findings locally?" with **[Q]**, **[N]** and **[E]** only.

Then ask, saying "public issues" for "issues" when the split's `is_default` is true (§4), and otherwise, an unsplit repository included, adding "(public if that repository is public)" after its name:

"Submit these findings as issues on {workflow.health_check_repo}, filed with your GitHub account?

- **[Y]** Yes: submit the bug findings; friction and gap findings stay local
- **[A]** All: submit every finding, friction and gap included
- **[N]** No: discard all findings
- **[E]** Edit: let me revise before submitting
- **[Q]** Queue locally: save every finding to `{workflow.health_check_queue_path}/`, submit nothing

You are the final filter. Reject any finding that does not reflect a real issue you observed."

**HALT and wait for input.**

- **[Y]** or **[A]** → proceed to §5 (severity routing).
- **[N]** → append `health-check: discarded` (§1), display "Findings discarded. Workflow complete." and return.
- **[E]** → let the user keep, modify or remove findings, and make each change in that finding's draft. A change to a finding's severity, stage, section, defect name or short description changes its fingerprints or its title, and a stage moved into or out of `health-check` changes its route (§4): run §3's call again, and when `{fp}` changed, write the draft anew as `hc-body-{fp}.md` under the new `{fp}`. Then show the revised findings and ask again.
- **[Q]** → write every finding, whatever its severity, to the local queue (§5c) with the reason "The review gate queued these locally."

### 4-headless. Unattended routing (no human at the gate)

In headless (`-H`) nobody answers the gate, so this routing takes its place:

- If `{workflow.health_check_autosubmit}` is **false** (the default): queue every finding locally (§5c), since nobody approved a public post, with the reason "Headless runs queue every finding while health_check_autosubmit is off." (a `health-check` finding takes §4's)
- If `{workflow.health_check_autosubmit}` is **true**: live-submit the `bug` findings but a `health-check` one (§5a) and queue the friction and gap findings (§5c) with the reason "Headless runs never submit friction or gap findings." (a `health-check` finding of any severity is queued with §4's) A match takes **[S]** (§5a-i).

Never block or delay the final headless JSON emit: Finalize emits it only after this step returns, and an automator is waiting on it.

## 5. Severity routing (attended [Y] and [A])

- **[Y]**: each `bug` finding but a `health-check` one live-submits (§5a). Each `friction` and `gap` finding, the most subjective kinds and the ones that draw the most near-duplicates, goes to the local queue (§5c) with the reason "Friction and gap findings stay local unless you choose [A]."
- **[A]**: every finding but a `health-check` one live-submits (§5a).
- A `health-check` finding, under either, goes to the local queue with §4's reason.

### 5a. Live-submit: dedup, create

For each finding routed to live-submit, unless the repository is unsplit (§4):

**1. Check the seen-cache via the script:**

```
uv run {skill-root}/scripts/health_check_fp.py seen --fp {fp} --legacy-fp {legacy_fp} \
  --cache "{workflow.health_check_seen_cache}" --repo "{workflow.health_check_repo}"
```

→ `{"seen", "status", "record", "matched_on", "opening_line"}`. Where the record names an issue, the script reads that issue's state itself: never run that check yourself, and never put a recorded URL into a shell command. If the call fails or prints no JSON, log its error and treat it as `unseen`. Act on `status`:

- `handled`, the only verdict that suppresses: skip the finding and log `"{fp}: already handled on {record.date}, {record.issue_url}, skipping"`.
- `unseen` or `unrecognized`: report it as a first sighting. When `matched_on` is `legacy_fp`, log `"{fp}: legacy record {legacy_fp} may be another defect, reporting"`.
- `regression` or `possible-regression`: report it, opened by the line below.

**Opening line** (`regression` and `possible-regression`). Write `opening_line` exactly as printed at the top of the finding's draft, above `## Workflow`, with a blank line after it. A `regression` takes `{regression_title}` in place of `{title}` and records its outcome with `--regression` (§5b). A `possible-regression` keeps `{title}`, since its record cannot prove a recurrence, and records without `--regression`.

If adding the opening line to the draft fails, log its error and write the finding to the local queue (§5c) with the reason "Posting these to GitHub failed."

**2. Check GitHub CLI** with `gh auth status {host_flag}`. If it runs and fails, fall through to §5c with the reason "GitHub CLI is not available."

**A refused `gh` call.** When the session refuses `gh auth status` or any later `gh` call of §5a, so that the command never ran, make no further `gh` call in this check: write this finding and every live-submit finding not yet submitted to the local queue (§5c), with the reason "You declined a gh call; nothing was posted." in an attended run, and "A gh call was refused in this session; allow the health check's gh commands (see health_check_autosubmit) to submit unattended." in an unattended one.

**3. Remote dedup search**: one deterministic call, and a second only when the first finds nothing:

```
gh issue list --repo {workflow.health_check_repo} --state open --search "{fp} in:title" --json number,url,title --limit 1
```

An issue it finds reports this defect. When it finds none, search once more, for the section fingerprint in titles and bodies:

```
gh issue list --repo {workflow.health_check_repo} --state open --search "{legacy_fp} in:title,body" --json number,url,title --limit 5
```

Each issue this second search finds is a **possible match** (§5a-i).

If either search exits non-zero, it has not shown that no issue matches: log its error and send the finding to the local queue (§5c) with the reason "Posting these to GitHub failed."

**5a-i. If a matching open issue exists**, present, `{match_number}` and `{match_title}` being that issue's `number` and `title` from the search:

> "Matching report found: #{match_number}: {match_title}
>
> Your finding has the same fingerprint `{fp}`. Options:
> - **[R]** React (👍) on the existing issue — silent upvote, no comment
> - **[C]** React + comment with YOUR environment/evidence delta (only if it materially differs)
> - **[N]** Create a new issue anyway — only if you are certain this is a distinct defect
> - **[S]** Skip — do not submit this finding"

**Possible matches.** When the issues came from the `{legacy_fp}` search, list each one and present the same options under this opening instead:

> "Possible match: #{match_number}: {match_title} (one line for each issue found)
>
> It carries this section's fingerprint `{legacy_fp}`, which every `{severity}` finding in this section shares: it was filed by a version whose fingerprints carry no defect key, or it reports another defect in this section under another key, so it may report another defect. Pick **[R]** or **[C]** only if it reports this one, naming it when more than one is listed, and **[N]** if none does. Options:"

**Unattended default: [S].** Only the user decides a match. A run with nobody to ask (headless with `{workflow.health_check_autosubmit}` true) takes **[S]** at an exact or a possible match, so the finding goes to the local queue (§5c) with the reason "These may match an open issue on {workflow.health_check_repo}; review them before submitting.", and nothing is posted on a guess.

Execute the choice:

- **R:** `gh api {host_flag} -X POST repos/{owner_repo}/issues/{match_number}/reactions -f content='+1'`, then record `reacted` (§5b).
- **C:** the reaction call, then write the minimal env+delta body (the Environment table plus one sentence on what differs; no session narrative) with the Write tool to `hc-comment-{fp}.md` in the run folder, show the user its text, and run `gh issue comment {match_number} --repo {workflow.health_check_repo} --body-file "<run folder>/hc-comment-{fp}.md"`; then record `commented` (§5b).
- **N:** after an exact match, the open issue carries this same fingerprint, so a new issue under it would be closed as its duplicate: choose a more specific defect name that sets this defect apart (the more specific name the fix edits, or the case it covers, still in the source's words), run §3's call again with it and write the draft anew under the new `{fp}`, without a line the old verdict added. Then run steps 1 to 3 again for the new fingerprints and act on what they return as for any finding: the new `seen` verdict alone decides the opening line, the title and `--regression`. After a possible match, proceed to §5a-ii as is: that issue's `fp-*` label differs from `{fp}`.
- **S:** write the finding to the local queue (§5c) with the reason "You skipped these at the dedup gate." (the Unattended default's reason when nobody was asked).

If the reaction or the comment call exits non-zero, log its error and make no further call for this finding: **C** posts no comment after a failed reaction, and a reaction already added stays. Write the finding to the local queue (§5c) with the reason "Posting these to GitHub failed."

**5a-ii. If no matching open issue exists** (or the user chose **[N]**), create one.

**First, create the `{fp}` label**, which `--label {fp}` needs:

```
gh label create --repo {workflow.health_check_repo} "{fp}" --color "ededed" \
  --description "Health-check fingerprint dedup key"
```

If it exits non-zero (the label exists already, or you have no push access), that is no error: go on to the create.

**Then create the issue** from the finding's draft:

```
gh issue create --repo {workflow.health_check_repo} \
  --title "{title}" \
  --label "health-check,workflow-improvement,{severity},{fp}" \
  --body-file "<run folder>/hc-body-{fp}.md"
```

After a `regression` verdict, `{regression_title}` takes the place of `{title}` (§5a step 1).

**If `gh issue create` exits non-zero, run it once more without the `--label` line**, with the same title and body file: a reporter without push access can set no label, and the dedup Action labels the issue from its title.

After the issue is created, by the first run or the retry, record it (§5b) so this user does not re-report it while that issue stays open. If `gh issue create` fails on its retry too, log its error and write the finding to the local queue (§5c) with the reason "Posting these to GitHub failed."

After creating all issues, keep for §6 the line "{N} issue(s) created on {workflow.health_check_repo}:" and each URL.

### 5b. Record the outcome

Record each outcome that ties a finding to an open issue, via the script, with that issue's URL and today's date:

```
uv run {skill-root}/scripts/health_check_fp.py record --fp {fp} --cache "{workflow.health_check_seen_cache}" \
  --issue-url "{url}" --action created|reacted|commented --date {YYYY-MM-DD}
```

`created` after `gh issue create` succeeded, on its first run or its retry without `--label`, `{url}` being the URL it printed; `reacted` after **R** and `commented` after **C**, `{url}` being the matched issue's `url` from the search, also when the match came from the `{legacy_fp}` search. After a `regression` verdict, add `--regression`: the issue now tracks the recurrence, so it replaces the `resolved` record the fix left under `{fp}`. Nothing else is recorded: not a queued finding, not **[S]**, not a failed call. A queued finding is not an issue, and a record for it would suppress the same defect when a later attended run approves it.

The call prints `{"written", "fp", "record", "set_aside"}`. `"written": false` is no error: the script kept a `resolved` record. When `set_aside` is not null, tell the user (log it in headless) that `{workflow.health_check_seen_cache}` did not parse, so it was renamed to that path and a new cache was started, and that they keep its records by repairing that file and copying its entries into `{workflow.health_check_seen_cache}`. If the call fails, log its error and go on: a lost record costs at most a duplicate report, which the dedup Action closes.

### 5c. Local queue (every finding that stays local)

Each finding here carries the reason sentence its routing step gave it.

Write each such finding into `{workflow.health_check_queue_path}` with the script, `{title}` being the finding's `title`, or its `regression_title` only after a `regression` verdict whose opening line was added:

```
uv run {skill-root}/scripts/health_check_fp.py queue --queue-dir "{workflow.health_check_queue_path}" \
  --body-file "<run folder>/hc-body-{fp}.md" \
  --title "{title}" --repo "{workflow.health_check_repo}"
```

→ `{"path", "commands"}`: the file it wrote and the three commands that submit it. If the call fails or prints no JSON, log its error and list the draft itself in that file's place (it holds the same text), followed, in place of commands, by "Submit it as <https://armelhbobdad.github.io/bmad-module-ultracode-goal/health-check/#submitting-a-queued-finding-manually> says."

After writing the files, keep for §6 this block, once per reason when findings stayed local for more than one, each block listing its own files:

"{N} finding(s) saved locally:" then each path, each followed by its three `commands`, exactly as printed.

then:

"{reason sentence} Run a finding's first two commands to submit it as an issue (the first fails, harmlessly, when its label exists), or open one at <https://{host}/{owner_repo}/issues/new/choose>. Without push access to {workflow.health_check_repo}, run its third command alone instead: you can neither create a label nor set one, and the dedup Action labels the issue from its title."

With the repository unsplit (§4), leave out ", or open one at" and its link: there is no host to link. A block that lists no queue file, only drafts, ends with its reason sentence alone.

## 6. Close

Once every finding is routed, or none survived §3, append the one line `health-check: done, <n> filed, <n> upvoted, <n> queued, <n> already handled, <n> dropped` (§1), each count being the findings that took that route (an issue created; **R** or **C**; the local queue; a `handled` verdict; dropped in §3). Only then show the lines §5a-ii and §5c kept, in that order, followed by "Workflow complete.": display them in an attended run; in an unattended one, display nothing and wait for nothing, and log the kept lines alone. Then return.
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: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated 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: 196kUpdated Claude CodeCodexVerifiedInstall