work-hvn

Files (3)

• SKILL.md
• openai.yaml · agents/
• project-audit.md · references/

SKILL.md (first lines)

# Work

Move a project from its current truth to the strongest completion claim the evidence supports. Treat “perfect” as a rigorous closure standard, never as a guarantee that unknown defects cannot exist.

## 1. Discover before committing

Perform a bounded read-only pass before creating the implementation goal.

1. Resolve the named project, canonical repository or working surface, applicable `AGENTS.md` files, local instructions, delivery destination, and current dirty state. Do not assume the current directory or first checkout is authoritative.
2. Inspect relevant product and architecture docs, memory, branches and worktrees, recent changes, open PRs, CI, deployments, runtime surfaces, and the live tracker. Verify drift-prone facts against current state.
3. Read [project-audit.md](references/project-audit.md) and apply only the lenses relevant to this project and outcome.
4. Reproduce suspected failures or inspect the failing path. Separate `confirmed` findings from hypotheses.
5. Use current primary sources when platform behavior, dependencies, APIs, security guidance, regulations, or recommendations may have changed.
6. Rank confirmed gaps by blocking impact, user harm, risk, confidence, dependency order, and leverage. Prefer the highest-impact gate that unlocks or invalidates downstream work.
7. For every executable software project, perform the bounded performance-candidate pass in section 4 and rank credible speedup opportunities alongside the other work.

Do not edit during discovery. Ask only when an undiscoverable choice would materially change the result or risk.

## 2. Frame one active goal

After discovery identifies real work and before mutation, call `set_goal` or the exposed goal-creation equivalent. If no goal tool exists, state that capability boundary instead of treating prose as an active goal.

The objective must include:

- **Outcome:** the user-visible project state to achieve.
- **Context:** the confirmed gaps or gates preventing it.
- **Constraints:** scope, safety, preservation, and approval boundaries.
- **Evidence:** tests, runtime proof, delivery proof, and re-audit required for the claim.
- **Done when:** every confirmed in-scope project-owned gap is closed, or only verified external, human-only, or approval-gated work remains.
- **Destination:** the branch, PR, deployment, release, device, tracker, or artifact that must reflect the result.

Do not narrow or replace the goal to escape unfinished criteria. Keep it active across continuation turns and complete it only after the closure audit passes.

## 3. Work the highest-value loop

Repeat while useful in-scope work remains:

1. Select the highest-impact confirmed gap whose dependencies are ready.
2. For substantive repository work, use `start-work-hvn` to establish the safe base, tracker surface, branch or worktree, dirty-state preservation, and first verification target.
3. Diagnose the root cause. For code changes, use `ponytail` when available and prefer the smallest correct change.
4. When the selected work is a performance candidate, follow section 4 and the full `speedup-proof-hvn` contract.
5. Lock important behavior with a regression test when practical; preserve validation, error handling, security, privacy, accessibility, and explicit requirements.
6. Implement only task-owned changes.
7. Verify from narrow to broad in proportion to risk: targeted tests, adjacent regression checks, type/lint/build, runtime interaction, visual or accessibility inspection, integration, deployment, and production truth.
8. Use `finish-work-hvn` when delivery, handoff, merge, deployment, or closeout is required. Prove the requested destination, not merely a local commit or intent.
9. Update the tracker when tracker truth is part of done.
10. Re-audit the fixed area, sibling instances, critical journeys, performance candidates, and delivery state; then select the next confirmed gap.

Keep a compact evidence ledger using only truthful states: `confirmed`, `fixed`, `tested`, `runtime-verified`, `delivered`, `external-blocker`, `deferred-by-user`, and `unverified`.

## 4. Prove performance opportunities

Run a bounded performance-candidate pass for every executable software project, even when the user did not report slowness.

1. Prefer existing profiler output, telemetry, traces, slow tests, query logs, or benchmarks. Otherwise inspect critical workloads for repeated scans, nested lookups, unnecessary allocations, N+1 I/O, render churn, duplicate filesystem work, and avoidable recomputation. Use only non-mutating evidence during discovery.
2. Rank candidates by execution frequency x input size x unit cost x confidence, then by user impact. Record `no-credible-candidate` when no realistic workload or evidence supports an experiment; do not manufacture optimization work.
3. For the highest-value credible candidate, invoke `speedup-proof-hvn` in `prove` mode. A `$work-hvn` invocation is not approval to edit an unseen optimization: present the exact required proposal and stop until the user explicitly approves it.
4. After approval, establish a repeatable baseline, apply only the approved change, verify preserved behavior, rerun the identical benchmark, and generate the native speedup report. Retain only a `PROVEN` result; reject the patch for `INCONCLUSIVE`, `REGRESSION`, or failed correctness and report `UNMEASURED` when no credible benchmark exists.
5. Re-audit after the experiment. Handle another material candidate only as a separate optimization with its own proposal and approval; never bundle candidates or reuse approval.

Record `no-credible-candidate`, the pending approval boundary, or the final `speedup-proof-hvn` verdict in the evidence ledger. A speculative candidate does not become a confirmed gap without measurement, but a confirmed material performance defect cannot be silently skipped.

## 5. Match proof to the claim

- Source inspection proves wiring and static invariants, not live behavior.
- Targeted tests prove the exercised behavior and failure cases; broader checks catch adjacent regressions.
- Equivalent repeatable before-and-after benchmarks plus passing correctness checks prove a speedup; complexity reasoning or one timing run does not.
- Runtime interaction proves user-visible behavior. Inspect rendered visual changes and capture interaction evidence when a still cannot prove the behavior and capture is practical.
- Remote branch, PR, deployment, store, device, or production checks prove delivery.
- Fresh-user, empty, degraded-network, permission-denied, and critical error paths are required when relevant to the outcome.
- If a check cannot run, mark it `unverified` and record the exact reason. Never weaken a meaningful gate to obtain green output.

## 6. Close only on evidence

Before completing the goal, confirm all applicable conditions:

- Every declared success criterion passes.
- No confirmed in-scope project-owned gap remains; release blockers and P0/P1 issues are not silently deferred.
- Targeted tests and risk-appropriate broader checks pass.
- Critical runtime journeys and important failure paths pass on the representative target.
- Discovered security, privacy, integrity, accessibility, performance, and reliability risks are fixed or explicitly dispositioned with evidence.
- The bounded performance pass is complete for every executable software project, and each selected candidate is `PROVEN`, rejected with evidence, or truthfully recorded as approval-gated or `UNMEASURED`.
- Required PR, merge, integration branch, deployment, release artifact, live behavior, tracker state, and documentation reflect current truth.
- Repository hygiene checks pass and unrelated work remains preserved.
- A final audit finds no new confirmed in-scope project-owned gap.

If these conditions pass, complete the goal. Otherwise continue, or report the exact external boundary without claiming the project is perfect or complete. If the user defers a confirmed gap, state the narrower readiness claim the remaining evidence supports.

## Cross fresh-task boundaries

At a mandatory fresh-task or policy-reload boundary, stop all mutation under the stale loaded policy.

1. Check whether the user explicitly authorized autonomous cross-task continuation or a successor task. Creating a task, including with `create_thread`, requires that explicit authorization; a request limited to the current task does not grant it.
2. When authorized and project-aware task tools are available, create and start the successor on the correct machine and project. Put a complete handoff in its initial instruction: outcome and current goal status; exact repository, branch, SHA, and worktree; completed evidence; blockers; preservation constraints; next discovery or goal action; and required destination.
3. Confirm through the task tools that the successor accepted the handoff and is active. Emit the app-required created-task directive (for Codex Desktop, `::created-thread{...}`) when required. Only then end the old task.
4. Do not repeat completed work or perform product mutations from the stale task. The successor must re-read current policy and verify drift-prone state before continuing.

If authorization or task capability is absent, report that exact boundary. If task creation fails, make up to two safe, meaningfully different attempts with the available project-aware tools, then report the exact tool, error, or authority blocker without broadening permission.

## Handoff

Lead with the achieved outcome. Concisely report the tracker item, branch/PR/base, changed files, verification, runtime and delivery evidence, performance-pass result, any speedup verdict and report link, remaining risks, exact blockers, and unrun checks when applicable. Never invent progress, screenshots, metrics, citations, tests, or release proof.

From henryvn27/agent-skills, MIT.

More from henryvn27/agent-skills