module-health-update
Refreshes health for every declared module in one pass: the test-driven rollup, then the session-evidence sync, through the existing module-health rollup and sync verbs. Use when the user asks to update or check module health, after a batch of changes, or when a module still holds its onboarding stub.
- License 许可
- MIT
- 所属仓库
- Eliyce/paqad-ai
- 最近更新
- 2026-11-13
- Stars
- ★ 8
- Forks
- 0
01 前言 Front Matter
- name
- module-health-update
- metadata
- { "cacheable": "false", "model_tier": "fast", "paqad-meta": "skill.meta.yaml", "output_format": "markdown" }
- description
- Refreshes health for every declared module in one pass: the test-driven rollup, then the session-evidence sync, through the existing module-health rollup and sync verbs. Use when the user asks to update or check module health, after a batch of changes, or when a module still holds its onboarding stub.
02 资源文件 9
- 参考文档agents/openai.yaml347 B
- 资产文件assets/templates/update-summary.md910 B
- 参考文档references/update-vs-rollup.md2.4 KB
- 脚本scripts/is-blocked.sh1.1 KB
- 脚本scripts/list-blocked-metrics.sh1.4 KB
- 脚本scripts/list-unattributed.sh1.1 KB
- 脚本scripts/list-updated.sh1.1 KB
- 脚本scripts/refresh.sh1.5 KB
- 参考文档skill.meta.yaml244 B
03 SKILL.md 正文
What It Does
Refreshes the health of every module in the project in a single pass, combining the two complementary update paths so a profile is never left frozen at its onboarding stub:
| Pass | Source | Fields it updates |
|---|---|---|
| rollup | The active stack pack's declared coverage + test reports, attributed to modules via module-map.yml sources: globs. |
coverage_pct, tests_passing, tests_failing, tests_total, change_velocity |
| sync | Pending session evidence + the changed-files list + verification status. | defect_frequency, contract_stability, verification status, tier |
Order matters: rollup first (report context), sync second (diff + verification context). The two write to different fields of the same .paqad/module-health/<slug>.json record and never conflict.
This is the on-demand counterpart to the automatic refresh that the verification backstop performs on every completion. Run it when you want to recompute everything at once.
Use This When
- A user prompt matches the priority-225 router rules (
update module health,refresh module health,update all module health,update modules health,check module health,recompute module health). - You have just landed a batch of changes and want every touched module's tier brought current before reporting.
- A module's profile still reads
tier: unknownwith all metricsnull(the onboarding stub) and you want to populate it.
Inputs
- The active stack pack's
module_healthblock: declaressource_rootsplus the coverage / test report formats and paths. When absent, the rollup pass recordsblocked: module_health_unknownand is skipped; the sync pass still runs. module-map.yml(read-only) for slug attribution.- Pending evidence under
.paqad/module-health-evidence/and the changed-files list, consumed by the sync pass.
Procedure
This skill carries the orchestration logic only. The deterministic plumbing lives in scripts/ and the output shape lives in assets/templates/: do not re-derive either in the LLM layer.
- Run the refresh, which runs both existing CLI verbs in order and emits one combined JSON object
{ "rollup": <report>, "sync": <result> }:
It shells out tobash scripts/refresh.sh [project-root]paqad-ai module-health rollup --project-root <root>thenpaqad-ai module-health sync --project-root <root>. No new command is introduced. - Pipe that JSON through the helper scripts rather than parsing it yourself:
scripts/is-blocked.sh: was the rollup pass blocked (module_health_unknown)? Informational only; the sync pass still ran.scripts/list-blocked-metrics.sh: per-moduleblocked_metricswarnings (config gaps, not Decision Pause packets).scripts/list-updated.sh: slugs the sync pass moved this run.scripts/list-unattributed.sh:MM-ADDcandidates for the module-map reconciler.
- Read back
.paqad/module-health/<slug>.jsonfor every module to get each resultingtier. - Render the summary by filling
assets/templates/update-summary.mdwith the helper output. Do not hand-write the table. - For any
unattributed_files, route the user to the module-map reconciler (MM-ADDcandidates).
Output Contract
- Per-module records written to
.paqad/module-health/<slug>.jsonin the schema-v2 shape. - A
## Module Health Updateblock and a## Unattributed Coverage Filesblock, both rendered fromassets/templates/update-summary.md, never authored inline.
Escalate / Stop Conditions
- Never fabricate or zero a metric. When a signal cannot be computed it stays
nullwith the reason inblocked_metrics: surface it, do not invent a value. - Do not add a new
paqad-aicommand for this workflow. It wraps the existingrollupandsyncverbs only.
Scripts
Deterministic plumbing: do not re-derive these in the LLM layer.
scripts/refresh.sh [project-root]: runs rollup then sync; always exits 0 so a blocked rollup never aborts the sync pass; prints{ rollup, sync }JSON.scripts/is-blocked.sh [report.json|-]: exit 1 with the rollup blocked reason on stdout, else exit 0 +none.scripts/list-blocked-metrics.sh [report.json|-]: sorted<slug>: <reason>, <reason>lines.scripts/list-updated.sh [report.json|-]: sorted slugs the sync pass updated.scripts/list-unattributed.sh [report.json|-]: sorted unattributed file paths (MM-ADDcandidates).
Assets
assets/templates/update-summary.md: markdown template for the## Module Health Update+## Unattributed Coverage Filesblocks.
Resources
references/update-vs-rollup.md: how this whole-project refresh relates to the narrower rollup and sync paths.runtime/base/skills/module-health-update/agents/openai.yaml: agent interface metadata.runtime/base/skills/module-health-rollup/SKILL.md: the lower-level rollup-only skill this workflow builds on.src/module-health/rollup.ts: the rollup engine.src/planning/module-health-updater.ts: the evidence sync engine.runtime/base/skills/module-map-reconciler/SKILL.md: sibling skill that consumesunattributed_filesasMM-ADDcandidates.
04 同仓库更多 Skills
sample-skill
Sample bundled skill fixture
processing-invoices
Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.
processing-invoices
Turns a supplier invoice into one ledger line. Use when a supplier invoice arrives and needs booking.
understand-idea
Chat and Claude Code: Step 1 of the discover journey: clarifies the goal, who benefits, success and constraints into the idea block. Use when the journey directs it to step 1, not directly.
size-work
Chat and Claude Code: Suggest a size for a ticket from comparable finished work, as a labelled suggestion the team still owns. Use it when someone asks "how big is this?", "roughly how much work is ABC-12?", or wants a backlog item sized. It finds the team's sizing scale at first use, picks two to five of the closest finished tickets with links, and gives a size or range with the drivers behind it and a confidence of low, medium or high, lowered and explained when the area's documents are template text. Every result is labelled a suggested size, never a date or a commitment. It writes nothing into the size field unless the user says "set it", and it refuses to overwrite an existing size unless the user asks to replace it. Produces the sizing block of the record.
refine-ticket
Chat and Claude Code: Improve one or more existing tracker tickets without losing the author's intent. Use it when someone wants a ticket read, diagnosed and tidied up ("this ticket is vague", "fix up ABC-12", "split this, it's too big"). It reads each ticket in full and snapshots it with its last-updated time, says what is wrong with evidence, and proposes a field-by-field before and after change set limited to summary, description, labels, parent, links and new child tickets on a split. It writes nothing until an explicit "apply it" bound to that exact change set, re-checks the ticket for conflicting edits just before writing, never replaces rich descriptions with plain text, never deletes or closes a ticket, and reads each ticket back after applying. Produces the existing and changes blocks of the record.