Skip to content
Skills Library
Management & product · Automation

honestdocs

/honestdocs

Keeps this project's development documents (decisions, designs, plans, research, postmortems, standing rules in {{root}}/) true with the honestdocs CLI. Use when starting a session, before designing or building something non-trivial, when committing work that a document describes, when closing out work, or when asked why something is built the way it is.

Repository
honestdocs ↗
Licence
MIT
Last repository change
28.10.2026

Assessment and security

95/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 28.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Keeps this project's development documents (decisions, designs, plans, research, postmortems, standing rules in {{root}}/) true with the honestdocs CLI. Use when starting a session, before designing or building something non-trivial, when committing work that a document describes, when closing out work, or when asked why something is built the way it is.

Original author description

Keeps this project's development documents (decisions, designs, plans, research, postmortems, standing rules in {{root}}/) true with the honestdocs CLI. Use when starting a session, before designing or building something non-trivial, when committing work that a document describes, when closing out work, or when asked why something is built the way it is.

How it works

  1. When a session starts
  2. Before building
  3. While building
  4. Finishing
Original SKILL.md headings · 68 lines, 417 words
SKILL.md preview
---
name: honestdocs
description: Keeps this project's development documents (decisions, designs, plans, research, postmortems, standing rules in {{root}}/) true with the honestdocs CLI. Use when starting a session, before designing or building something non-trivial, when committing work that a document describes, when closing out work, or when asked why something is built the way it is.
---

# Development documents with honestdocs

`{{root}}/` is the project's long-term memory. Every document is Markdown with a small
frontmatter block; `INDEX.md` is generated. **The code is the truth** — where a document
and the code disagree, believe the code and correct the document.

## When a session starts

```sh
{{command}} brief
```

Work in progress with its next unticked items, what is planned, what changed lately,
and the rules in force. Read the in-progress document you are continuing — its Log is
the hand-over from the last session.

## Before building

1. **Has this been weighed before?** `{{command}} search <words>`; with
   `--section alternatives` it shows only what was considered and rejected, with the
   reason. Superseded and abandoned documents are included on purpose. Do not propose a
   rejected option again without saying what has changed.
2. **Which rules apply?** `{{command}} rules` lists the numbered rules in force and the
   tests that prove them. Go through the `before-you-build` checklist in `{{root}}/rules/`.
3. **Open a document** for anything non-trivial:

   ```sh
   {{command}} new <area> <slug> --type design --title "Token rotation"
   ```

   Types: `design` (how it should work), `plan` (ordered steps, checklist), `research`
   (a question and sourced findings), `decision` (one choice, MADR), `postmortem` (what
   went wrong, with evidence), `reference` and `rule` (living documents, edited in place).
   Fill *Alternatives considered* — it is the part people and agents need most later.

## While building

- End every commit message that does the work with a trailer line:

  ```
  {{trailer}}: 2026-11-02-token-rotation
  ```

  That is how `{{command}} index` learns which files the document touched. Several ids:
  comma-separated or one line each.
- Tick checklist items (`- [x]`) as they land. Add dated notes to the Log.
- Never write `progress`, `files`, `superseded-by` or `updated` by hand. Write only
  `title`, `status`, `supersedes`, `related`.
- Replacing a document: `supersedes: [<old id>]` in the **new** one, then
  `{{command}} index` marks the old one.
- A rule changed: edit its rule document in place and add a Log line — never a second
  document beside it.

## Finishing

```sh
{{command}} done <id>              # refuses while checklist items are unticked
{{command}} done <id> --abandoned  # dropped on purpose; the reason goes in the Log
{{command}} status <id> current    # living documents: draft | current | retired
{{command}} index && {{command}} check
```

`check` exits 1 on anything that makes the set lie. A change is not finished while a
document or rule it affects still describes the old behaviour.

Every query command takes `--json`. The method in full: `{{command}} guide`.

Versions

The database has no other skills named honestdocs.

Database snapshot: 13.11.2026 · package version 8ee9aef57829 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 85development-log
    Maintain development plans, experiment records, decisions and handoffs during substantive engineering work. Use when implementation or supplied test evidence changes the recorded state of a project.
  • 91writing-plan-documents
    Use when writing any plan document or product spec — project plans, PRDs, product specs, proposals, implementation plans, or design docs. Applies ASD-STE100 Simplified Technical English as a writing style layer alongside other planning skills like superpowers:writing-plans.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.