docs: rewrite habit snooze spec for humans by ASHWATHRAM007 · Pull Request #197 · habit-hooks/habit-hooks

ASHWATHRAM007 · 2026-09-25T07:05:07Z

Summary

Rewrite docs/habit-snooze.spec.md for human consumption.
Make the document example-first and easier to follow.
Keep the documented habit-snooze behavior and executable examples intact.
Reduce implementation-focused explanation and unnecessary historical detail.

What changed

The spec now explains the user-visible behavior through focused examples covering:

unsnoozed and snoozed issues
findings disappearing when all issues are snoozed
older/bare snooze entries
empty indexes
--prune
--list
invalid indexes
snoozes expiring when approved files change
file anchors differing from issue keys
issues without usable file anchors

No application behavior or source code was changed.

devill

First of all, thanks for the effort put into this! Bellow are some notes on what should still be changed.

I read up until "## An entry that records nothing keeps holding" but I think I would be repeating the same things a couple of times.

The initial plan to keep all of the examples was sound, but looking at the PR it seems to me that some of them need to be converted into unit tests and removed from the document.

In general keep what the user (human or agent) needs to understand, and remove implementation details that might actually change in the future. Those should be more unit level test.

devill

-    ]
-  }
-]
+[{"smell": "loose-equality", "details": { "maxAllowed": 0 }, "issues": [{"key": "src/x.ts", "details": { "file": "src/x.ts", "line": 1 }}]}]


I'd keep the formatting, so as to make sure the result is easy to parse for the human eye

devill · 2026-09-25T08:46:24Z

-An entry written before approvals were recorded — a bare key — cannot be contradicted, so it keeps holding however the file changes, until the next `--snooze` records it. A project upgrading therefore never finds its existing snoozes re-arming on their own; each one arms the first time it is approved again.
-
-The file here is edited after the index was written, and the issue stays dropped.
+An entry written as a bare key has no file content to compare, so it keeps holding regardless of file edits until updated by `--snooze`.


"bare key" needs explanation here. I also wonder if the naming could be improved here.

Looking at it more, I think this whole section really needs clarification. This seems like relevant nuance to how snooze works, but the explanation needs to be more user focused.

devill · 2026-09-25T08:48:51Z

-A snooze records the **approved content**: `--snooze` stores, per file the key is anchored to, the content that file held, and an issue stays dropped only while its file still holds it. Editing the file brings its issues back, and `--snooze` again approves what is there now — described [below](#an-edited-file-brings-its-issues-back-until-it-is-approved-again). The `snooze-until-changed` transformer is kept as a deprecated alias of `snooze`: what it was the opt-in for is the only behaviour.
+`--snooze` records the approved content of each anchored file. An issue stays snoozed while its normalized content hash (converting CRLF to LF) matches; editing the file reactivates the issue. Running `--snooze` again approves the current state. The `snooze-until-changed` transformer is a deprecated alias of `snooze`.

 ## An unsnoozed issue passes through


I feel like the section headers could also use some improvement. They should be a bit more user benefit focused. For example this one could be "By default items pass through"

devill · 2026-09-25T08:55:15Z

@@ -57,71 +40,36 @@ habit-snooze | jq .

 ## `--snooze` records an issue's key into the index


Snooze remaining issues

devill · 2026-09-25T08:57:36Z

+# habit-snooze — ignoring findings you have approved

-Snoozing is a **transformer** ([architecture.md](architecture.md)): a `findings → findings` step that drops the issues a project has chosen to ignore and passes everything else through. It sits at the outermost level of the run, where it sees every finding.
+`habit-snooze` is a transformer ([architecture.md](architecture.md)) that removes approved issues and passes everything else through.


I'd add one leading paragraph about the user benefit. Something like:
"When installing habit-hooks for the first time, or tightening the rules you may end up with more warnings then what you want to fix in one go. In these situations you can snooze them, and they will come back the first time the file is changed again. This allows you to fix them gradually."

devill · 2026-09-25T09:03:36Z

 src/x.ts
 ```

 ## A snoozed issue is dropped from its finding


This should be converted into a unit test. The agent has treated the documentation as unit level tests, which resulted in examples that show implementation details. From a user perspective the mechanics of how the snoozes are stored are not as relevant.

devill · 2026-09-25T09:03:46Z

@@ -145,115 +93,65 @@ habit-snooze | jq .

 ## A finding loses its only issue and disappears


devill · 2026-09-25T20:17:42Z

Thanks for this, Ashwath — the rewrite made the doc much easier to follow, and the PR is now rebased and merged. You did the hard part of filtering the document down to the important parts.

I still decided to edit it further, but that was more restructuring than cutting. Below is a list of things I did and why I did them. In case you wish to pick up similar issues, this might help.

You correctly removed the tests that are better as unit tests, but in the process you also removed the setup steps. Those had to be re-added, so the build doesn't fail.
I restructured the document to have the examples right after the section they demonstrate. This way it reads better, and there is less repetition.
I also decided to change the examples to make sure they better serve the understanding. Instead of an imaginary sensor, the examples now use a real sensor with real findings. (Also showing the full output right now instead of just file names.)
Once done I noticed that the setup had to be repeated at the start of every section, but the document read better as a continuous story. So a (example continued from previous section) annotation was introduced to make sure the sections can use a single context.
The removal of the unit test like examples meant that case was no longer covered. A unit test was implemented to replace that test case.

docs: rewrite habit snooze spec for humans

c87e174

devill requested changes Sep 25, 2026

View reviewed changes

ASHWATHRAM007 and others added 6 commits September 25, 2026 19:17

docs: simplify habit snooze spec and more user focused

7e0e32c

docs: make the habit-snooze spec examples runnable

8a81f06

Restructure habit-snooze.spec.md

f064b6b

docs: make the restructured snooze spec examples run

2855ae3

test: let spec sections continue from the previous section

345ad4c

docs: tell the snooze spec as one continuous example

2b16176

devill merged commit b52ce6e into habit-hooks:main Sep 25, 2026

Navigation Menu

Repository navigation

docs: rewrite habit snooze spec for humans - #197

docs: rewrite habit snooze spec for humans#197
devill merged 7 commits into
habit-hooks:mainfrom
ASHWATHRAM007:docs/rewrite-habit-snooze-spec

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		@@ -57,71 +40,36 @@ habit-snooze \| jq .

		## `--snooze` records an issue's key into the index

		@@ -145,115 +93,65 @@ habit-snooze \| jq .

		## A finding loses its only issue and disappears

Conversation

Summary

What changed

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants