state

Generates OKR-shaped status reports with scored key results, blockers, and evidence sections.

Updated Aug 6, 2021
One-click install
npx skills add https://github.com/the-homeless-god/dotfiles --skill state-the-homeless-god
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: state
Source: https://github.com/the-homeless-god/dotfiles/tree/main/skills/state
Command: npx skills add https://github.com/the-homeless-god/dotfiles --skill state-the-homeless-god

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Long-running engineering work produces status updates that are either too vague to act on or too long to read. This Skill enforces a fixed report shape — one objective line, three to six key results scored against declared thresholds, the blocker, and what is needed from the reader — so a busy human can grasp where work stands in ten seconds while all evidence stays available below a divider. ## Core Features & Use Cases - Capped report head: The human-readable section is limited to 14 lines and 900 characters, with uncapped evidence (actions, omissions, provenance) placed below a --- rule. - Three-status scoring: Key results are marked achieved, missed, or unmeasured, with a strict rule that unverified claims can never be marked achieved. - Comparable reporting: Key results are reused from the work's acceptance criteria and re-scored each report, making two reports on the same work directly comparable. - Use Case: An agent running a multi-session refactoring initiative reports progress at each milestone: the reader sees the objective, which thresholds were met or missed, the current blocker, and exactly what decision is needed — without reading the full evidence log. ## Quick Start Use the state skill to report where this work stands, with one objective line, key results scored against their thresholds, the blocker, and what you need from me.

Frequently Asked Questions about state

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a status report for long-running engineering work?

Structure it as one objective line, three to six key results with declared thresholds and measured facts, a blocker line, and a request line. Keep the readable head under 14 lines and 900 characters, and place all evidence below a divider.

What is the difference between missed and unmeasured status in a report?

Missed means the metric was measured and fell short of its threshold. Unmeasured means it was never run, and the report must state why. The two are never collapsed, because they imply different next steps for the reader.

When should I not use an OKR-shaped status report?

Skip it when the answer is a single fact, when the reader explicitly asked for depth or explanation, or when delivering bad news that needs narrative context first. In those cases plain prose serves the reader better.

Why must every number in a status report include provenance?

A number without its source — which tree, commit, binary, or command produced it — cannot be verified or refuted by the reader. Provenance turns a claim into evidence the reader can independently check.

Can a status report mark unverified work as achieved?

No. A result asserted but not measured is marked unmeasured, never achieved. This rule keeps the third status meaningful and prevents reports from presenting guesses as verified outcomes.