Log deviation

Skill hiendinhngoc/unknowns/skills/log-deviation

Record a place where the code forced a deviation from the agreed plan. Use mid-implementation whenever reality contradicts the plan, or when the user says "log this deviation". The log feeds future planning and the merge quiz.From its SKILL.md

Install

npx -y skills add hiendinhngoc/unknowns --skill log-deviation

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

9 stars9 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

2.3 KB, 497 tokens by cl100k_base, as published. Nobody here has run it

Deviation Log

The plan said one thing; the code demanded another. Record it while it's fresh — these entries are the highest-value input to the next plan.

Where the log lives

In a git repo: docs/deviations/YYYY-MM-DD-<task-slug>.md at the repo root (create docs/deviations/ if needed). <task-slug> = short kebab-case name of the current task. Slugs are minted freely, so two sessions will name the same task differently: before creating a new file, list what already exists in docs/deviations/ and reuse the slug of any file that is plausibly this task — appending to it even if it's from an earlier day/session — rather than minting a near-duplicate.
Outside a git repo: write to the session scratchpad instead and tell the user the path.

Entry format (append, newest last)

## <YYYY-MM-DD HH:MM> — <one-line summary>
- **Plan said:** <what the plan/spec assumed>
- **Code forced:** <what was actually done instead>
- **Why:** <the real-world constraint that made the plan wrong>
- **Ripple:** <other plan steps this invalidates, or "none">

The heading carries the full date: the file spans days by design, and HH:MM alone goes ambiguous on the second session.

Discovered drift

Not every deviation is caught live. When work reveals that plans or docs already disagree with the shipped code (a stale roadmap item, a doc promising a design the code abandoned), log it with the same fields plus one more:

- **Found while:** <the current activity that surfaced it>

Date the heading with the discovery time; if the deviation's original date is known, name it in Code forced.

Rules

One entry per deviation, logged at the moment it happens — not batched at the end.
"Why" names the constraint (API limitation, hidden coupling, wrong assumption), never just "it didn't work".
If invoked with no deviation to log, ask what deviated rather than inventing one.
Do not commit the log automatically; leave staging to the user's normal flow.

What ships with it: 1 file

203 B alongside SKILL.md

agents/

openai.yaml203 B

Gives 0 of the 12 instructions most plan spec skills give in 497 tokens

Counted across 1,360 of the 2,617 authors here whose files we hold, read 2026-09-06

Ask one question at a timein 73 of 1360
Write the spec using the templatein 22 of 1360
Ask clarifying questions if neededin 19 of 1360, across 18 files
Wait for user confirmation before proceedingin 19 of 1360
Save plans to the plans directoryin 17 of 1360, across 13 files
Check for product marketing context firstin 16 of 1360, across 5 files
Read the plan file completelyin 16 of 1360
Order tasks by dependencyin 16 of 1360
Gather context from the conversationin 15 of 1360, across 9 files
Explore the codebase instead of askingin 15 of 1360, across 13 files
Wait for explicit user approvalin 14 of 1360, across 13 files
Quiz the user on the breakdownin 13 of 1360, across 7 files

Said here and by no other author read

Record deviations while fresh
List existing deviation files before creating new ones
Reuse plausible existing task slugs
Write to the session scratchpad outside git repositories
Log one entry per deviation when it happens
Ask what deviated if invoked without a deviation

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.