moilanik 191f9f4f2a refactor(ai-skills): harden control flow and reduce instruction drift

Tighten root/core control flow, add dedicated post-mortem, web, and
context-hygiene capabilities, and reduce instruction drift through clearer
ownership, conflict-priority handling, and README/docs workflow alignment.
This makes long-session AI behavior more deterministic while keeping the
instruction system compact and maintainable.

2026-04-21 16:01:21 +03:00

2.9 KiB

Raw Blame History

name	description	category	impact
documentation	Rules and structures for writing project documentation in Markdown. Use when creating, formatting, or updating markdown docs.	workflow	low

Documentation Instructions

Core Principle

Every document starts with the problem it solves — one or two sentences. Then a diagram if it clarifies, then content.

Document Workflow

Abstract -- write problem statement + section headings (+ top-level diagram if relevant) directly into the file. Do not propose the structure in chat first.
Align -- stop after writing the abstract. The human reviews it in the file and confirms or adjusts before any section content is written.
Section by section -- write ~50 lines at a time, then stop and wait. The human decides when a section is ready and asks for the next one. Do not ask "did this go in the right direction?" or prompt the user to continue.
Stay in scope -- if something is complex or unclear, stop and ask rather than guess
Review -- when done, AI asks: "Is anything missing?" -- user decides
Link check -- after finishing, scan other docs in docs/ for broken links or documents that should now link to this one

Diagrams

Abstract: one top-level diagram showing the full scope. Sections: add focused sub-diagrams to clarify specific parts.

Use Mermaid for flows, architecture, component relationships. Use ASCII trees for file/folder structures. When in doubt, include a diagram -- visuals are faster to read than text.

For contrast rules, sizing and diagram type selection: see mermaid.instructions.md

What Belongs in a Document

✅ Principles — how and why the system works ✅ Architecture — components, relationships, data flows ✅ Key decisions — why this approach over alternatives ✅ Scope boundaries — explicitly state what is out of scope and link to where it is covered

❌ Step-by-step commands — belong in README or runbooks ❌ Full code blocks — small illustrative examples only ❌ Troubleshooting — "if error X do Y" does not belong here ❌ All possible alternatives — pick the relevant ones, explain briefly when to use which

When the User Corrects Something

Fix only what was pointed out
Do not explain why you got it wrong
Do not add anything else at the same time

Scope

Keep each document tightly scoped to its title.

If a topic needs deeper treatment:

Ask: 'Should we create a separate document for X?'
If yes: write a short intro sentence and link to the new doc
Do not expand inline

Length

Increment: ~50 lines at a time, then check with user
Hard limit: 500 lines
If approaching limit: stop and ask user what to continue with

Rules

Follow the root-skill language policy.
No step-by-step commands -- those belong in README or runbooks
No changelog entries
No duplication between documents -- link instead

2.9 KiB Raw Blame History