Organise Docs

Long-task checkpoint cadence

• For any non-trivial task (including long efforts), run recurring checkpoint cycles instead of waiting for a single end-of-task wrap-up.
• At each meaningful milestone with commit-eligible changes, and at least once per major phase, invoke git-commit to create a small logical checkpoint commit once relevant checks are green and repo policy permits commits.
• At the same cadence, invoke organise-docs whenever durable learnings/decisions appear, and prune stale plan/ scratch artifacts.
• If either checkpoint is blocked (for example failing checks or low-confidence documentation), resolve or record the blocker immediately and retry before expanding scope.

Terminal state contract (must follow)

The skill is complete only when all of the following are true:

• Objective completion: the user-requested outcome is achieved, or explicitly marked blocked with concrete blocker evidence.
• Workflow completion: every required workflow step is resolved as done, blocked, or not-applicable, with brief evidence or rationale.
• Step-level terminal completion: each numbered subtask must have explicit completion evidence (artifact, command output, or written rationale) before advancing.
• Verification completion: required checks/validations for this skill are executed, or any unavailable checks are explicitly called out with impact.
• Findings completion (where applicable): report only evidence-backed findings; if no high-confidence critical findings are present, explicitly state that.
• Loop completion: no actionable in-scope next step remains under the current objective.

Stop only after this terminal contract is satisfied; otherwise continue iterating.

Terminal state examples (adapt to skill)

• done: requested outcome is delivered and required checks are completed (for example expected artifact/report produced and required validation command(s) passed).
• blocked: progress cannot continue after bounded retries because of a concrete dependency or access issue; blocker evidence and exact unblock action are reported.
• not-applicable: an optional step is explicitly skipped with reason (for example no remote configured, so push step is marked not-applicable).

Overview

Extract durable knowledge from the current conversation and convert it into high-signal repository documentation. Focus on decisions, principles, invariants, constraints, and rationale that remain useful over time.

Conversation-derived knowledge capture (must follow)

• On every invocation, audit the current conversation/session for durable knowledge that should not remain trapped in chat history.
• Explicitly look for decisions, principles, nuances, assumptions, options considered, rejected paths, constraints, preferences, invariants, failure modes, and unresolved-but-important questions.
• Update that knowledge in the most appropriate repository location before finishing: prefer existing canonical docs in docs/, then local decision logs or workflow docs, then active plan/ notes/handoffs when the content is still ephemeral or awaiting promotion.
• If a suitable section already exists, update it instead of duplicating it. If none exists and the knowledge is durable, create the smallest clear section needed to preserve it.
• Do not stop at code or doc edits alone; ensure the repository's notes/docs reflect the important knowledge established by the conversation so far.
• If an item materially affects future work but is not yet durable enough for docs/, capture it explicitly in plan/ with clear routing or promotion intent rather than leaving it implicit.

Continual compounding mode (must follow)

Run a compounding cycle after each substantial task.

• Treat a task as substantial when it includes multi-step debugging/investigation, meaningful code edits, non-trivial design decisions, or repeated back-and-forth that produced reusable knowledge.
• Keep a lightweight "write it down now" habit during execution so useful details are not reconstructed from memory later.
• Capture ephemeral exploration notes in plan/ while working.
• Promote durable learnings into docs/ before finishing the task.
• Consolidate duplicated scratch notes and prune stale plan/ artifacts after promotion.
• Keep docs/ evergreen and high-signal; keep plan/ disposable and short-lived.

Operating Mode

Apply documentation edits autonomously when confidence is high.

• Auto-apply doc edits without asking for permission when evidence is strong.
• Create, merge, split, move, rename, reorganize, and delete docs when this improves clarity and maintainability.
• Prefer one canonical doc or section per topic; if several artifacts say the same thing, merge them or leave a clear pointer instead of parallel truths.
• Do not be afraid to create a deep docs/ hierarchy (nested directories) when it improves navigability. Prefer a coherent structure over a flat, overloaded docs/.
• Make docs interrelate: add and maintain relative links between related docs, and keep an entrypoint index current (for example docs/README.md, plus per-directory README.md/index.md when useful).
• If confidence is not high, do not invent facts. Leave content unchanged or call out the uncertainty in the final summary.

Notes hierarchy and routing (must follow)

• Treat notes and snippets as flexible raw material; organization can evolve as understanding improves.
• Route ephemeral notes to plan/current/ and keep them concise, task-linked, and disposable.
• Route durable guidance to docs/ only after de-duplication and contradiction checks.
• Keep per-workstream notes near the workstream context (for example in its worktree/cwd notes file) and reflect only compact pointers in shared indexes.
• For multi-workstream/subagent efforts, keep a compact shared index (for example plan/current/notes-index.md) that links workstream notes and latest status.
• If plan/ cannot be created, keep an in-memory index and call it out in the report.

Workflow

1. Build the evidence set.

• Read the relevant conversation turns, edited files, and test outcomes before writing docs.
• Use only evidence-backed statements.
• Prefer concrete facts over interpretations.
• Keep temporary extraction notes in plan/current/ while building the evidence set.
• Gather relevant notes and snippets from active workstreams before consolidation so nothing important is dropped.

2. Filter for durable knowledge.

• Keep: decisions, principles, nuances, assumptions, options considered, trade-offs, rules, invariants, failure modes, constraints, preferences, and stable process guidance.
• Drop: one-off status, temporary debugging traces, timestamps, and short-lived implementation trivia.
• Rewrite relative time phrasing into evergreen language.
• Mark every retained item as either promote to docs or keep ephemeral in plan.

3. Consolidate contradictions and ambiguity.

• Detect conflicting statements and collapse them into a single canonical statement.
• Use this tie-break order: current code/tests, explicit user instructions, then older docs.
• Replace vague wording with explicit terms, units, and constraints.
• When docs use repeated structured entries such as Decision: blocks, run a quick duplicate-title sweep after merges or conflict resolution so accidental duplicate entries do not survive as competing sources of truth.

4. Route and reorganize docs.

• Prefer updating existing relevant docs first.
• Create new docs when the existing structure cannot hold content clearly.
• Merge fragmented docs when they duplicate scope, and name the surviving canonical location.
• Split overloaded docs when mixed topics reduce clarity.
• Reorganize notes into a clear hierarchy when raw notes have grown large or hard to navigate.
• Prefer making the structure explicit (nested directories + topic indexes) rather than relying on tribal knowledge. Avoid orphan docs by linking them from at least one index or related doc.

5. Write concise, structured updates.

• Use explicit sections or bullet entries that are easy to scan.
• For decisions, include: Decision, Context, Rationale, Trade-offs, Enforcement.
• Capture inferred decisions only when conviction is high and evidence supports the inference.
• Reference concrete enforcement points such as tests, modules, or invariants when known.
• Avoid duplicating existing text; tighten or replace stale wording instead.

6. Apply preservation checks before destructive edits.

• Never destroy potentially valuable information.
• Before deleting or heavily consolidating a doc, migrate all unique valuable content into a retained destination.
• Treat rationale, constraints, invariants, risk notes, and behavioral contracts as valuable by default.
• If value is uncertain, preserve the content in a compact retained section rather than deleting it.

7. Validate consistency before finishing.

• Check that new documentation matches current code and tests.
• Fail fast on contradictions: do not publish a doc update that conflicts with known behavior.
• Remove low-confidence speculative claims.
• For structured decision logs, verify each decision title appears only once unless an intentional repeated title is explicitly justified.
• Run one final consolidation sweep for duplicate sections, orphan notes, and contradictory statements before finishing.

8. Report what changed.

• Summarize files updated and the durable knowledge captured.
• If shared skill definitions were updated, list the skill files changed and the new reusable rule(s).
• Call out removed or consolidated docs and where preserved content was moved.
• Include a preservation map for destructive edits: source_doc -> destination_doc/section.
• List remaining ambiguity only when confidence was not high enough to resolve it safely.
• Keep the report short by default.
• Include What got faster next time only when the docs change actually improves a repeat workflow in a concrete way.
• Include Plan consolidation and prune only when plan/ artifacts were actually retained, merged, or deleted.
• If a repeated invocation produced a verified no-op and no new durable evidence appeared, report that explicitly and stop instead of reopening the same docs pass.

Quality Bar

• Keep docs evergreen and stable; avoid date-anchored wording unless dates are required for correctness.
• Preserve fail-fast intent and do not document silent fallback behavior unless it is explicitly desired.
• Prefer simple language and explicit statements over abstract summaries.
• Ensure every added line helps future contributors make better decisions faster.
• Default to high-confidence autonomous changes; do not block on avoidable questions.

Decision Entry Template

Use this structure when recording a new decision:

Decision:
Context:
Rationale:
Trade-offs:
Enforcement:

Skill composition

When this skill is triggered, compose other skills as needed:

• Use setup when the repo lacks the baseline docs/decision/workflow structure needed for durable documentation.
• Use investigate when the evidence set is incomplete or contradictory enough that documentation would otherwise rely on guesswork.
• Use verify to confirm that updated docs still match current code, tests, and workflow behavior when the mapping is non-obvious.
• Use git-commit or checkpoint after a meaningful docs promotion pass when the changes are verified and commit-eligible.

If there is a conflict, documentation integrity wins: do not let companion skills push low-confidence or speculative statements into durable docs.