Capture and Organize Project Decisions

User Thoughts persists the user's project decisions and constraints into a project-local knowledge base called mdbase, so that any later session or agent can recover the user's intent without re-deriving it. It records intent and does not replace normal task execution: if the user says "make the button red", the agent both makes the change and records the preference when persistent project memory is useful. It is an MIT-licensed community skill by JularDepick, triggered by the /user-thoughts or /ustht commands, or when the user discusses architecture, tech stack, rules, UI/UX or project memory.

The flow is: the agent spots persistent project intent and writes it to a raw log, /ustht sortin groups raw entries into the organized mdbase, and /ustht mdbase show exposes that memory. Runtime data lives in a .ustht/ folder in the project: define.ini, raw/ and ignored/ day files (yyyy-mm-dd.md), an mdbase/ folder with backlog.md, an index and details/ dimension files such as rules.md, plans.md, ui/outline.md, ui/details.md, dev-stack.md and general.md, and an export/ folder. The define.ini file holds SKILL_STATUS, INSTANT_STATUS and LAST_SORTIN, and is always rewritten whole rather than appended to.

Four runtime modes exist. In passive mode (INSTANT_STATUS=off) only explicit commands run. In instant mode (INSTANT_STATUS=on with SKILL_STATUS=on) relevant thoughts are captured as they appear. Ignore mode marks a temporary interval that must not be recorded. In read-only mode, when read, write or bash tools are missing, show commands still work and write commands explain that data cannot be persisted.

Commands cover status (init, status, skill, instant, each with on or off), maintenance (sortin and resort, both with --dry for a preview), ignore management (ignore start, ignore end, ignore --last, ignore show, or a message suffix of /ustht ignore), and review and export (raw, mdbase show, mdbase export, import <path>). Commands chain with &&. Bundled Python helpers handle mechanical steps: status.py, init.py, show_raw.py, show_mdbase.py, sortin.py, write_raw.py, toggle.py and ignore_ops.py; resort has no script because it needs semantic review by an agent.

Language policy: bundled files, scripts and templates are written in English, command output follows the user's current language when reasonable, and raw thoughts keep the user's original wording, with no translation, summary or cleanup unless requested. Clear natural-language requests map to commands: turning on project memory enables the skill and instant capture, stopping recording starts an ignore interval, organizing what was said runs sortin, showing what is remembered runs mdbase show, and ignoring the last note runs ignore --last; ambiguous intent gets a short clarification instead of a guess. A message that mixes a command with a thought runs the command and records the preference without recording the command text. resort marks dimensions deprecated instead of deleting them, and sortin appends entries under date headings in the matching dimension files.

Use it when the user states or revises project rules, constraints, preferences or requirements; architecture, tech-stack, data-model, deployment or workflow decisions; UI/UX direction, copy standards or design rationale; backlog items, rejected options or decisions future agents should inherit; or gives a direct skill command.

Do not use it for unrelated small talk, transient chatter or content the user asks to ignore. The skill records intent but does not check whether an idea is correct, feasible, secure or consistent. Dimension assignment relies on agent judgment and can be corrected with a later reorganization pass. There is no file locking, so multiple agents must coordinate before running maintenance. The runtime folder can hold sensitive information and nothing is redacted; use ignore commands or repository hygiene for secrets.

In instant mode each independent thought becomes one raw line in this format:

- [14:30] Make buttons use 8px radius | suggested-dim:ui/details
- [14:45] Login should use a dark theme | suggested-dim:ui/outline
- [15:10] Use REST APIs, not GraphQL | suggested-dim:dev-stack

Original wording is kept, including negations, numbers, links and tradeoffs, and one message with several decisions is split into several records. If a day collects more than five raw entries, the agent suggests running sortin.

sortin is soft maintenance: it reads unprocessed raw files, parses entries and suggested dimensions, appends them under date headings in the matching mdbase files, marks each raw file with <!-- processed --> as its first line, and updates LAST_SORTIN and the index. Classification priority is a user-specified dimension, an exact existing dimension, the closest existing dimension, then general.md. resort is hard maintenance: it reviews all mdbase files, removes duplicates, moves entries to better dimensions based on the user's own wording, and marks deprecated dimensions rather than deleting them. When statements conflict, the newest one is treated as current and the older one is kept as history. After sortin it reports counts per destination file. import scans markdown under a safe project-local path and merges only project-relevant decisions, tagged with their provenance.

Safety rules keep all writes inside .ustht/, allow dimension names of lowercase letters, digits and hyphens with / for subdirectories only, forbid .., backslashes, spaces, absolute paths and reserved names (backlog, readme-ai, export, raw, ignored, define, general), refuse to execute user-provided shell commands and never silently delete history.

It suits developers and product owners who work with several agents or sessions on one project and need the user's decisions, rules and design preferences to survive between them.