All decisions

Product and technical decisions on deciwa. All decided by Daniel; they are binding requirements for every feature and every piece of code. Business decisions (pricing, licence, market) are kept outside this repository.

A new decision comes from an approved proposal in the technical details – see Working on deciwa.

ID	Title	Decided
DEC_PURPOSE	deciwa is a review and decision tool for everyone who works with docs and code	2026-10-17
DEC_NO_ENFORCING	deciwa collects, evaluates and shows; it does not watch that decisions are kept	2026-10-17
DEC_VERDICTS	Feedback verdicts plus quick actions for the AI	2026-10-17
DEC_FREEZE	New verdict freeze	2026-10-17
DEC_DECISION_IS_APPROVAL	A decision is an approved statement, not an extra object	2026-10-17
DEC_NO_MARKERS	No markers in the source; elements come from the content	2026-10-17
DEC_FORMATS	Formats: text, HTML, Python, C, JS, TS, rST, Markdown, AsciiDoc	2026-10-17
DEC_HOVER_SELECT	Format objects are highlighted on hover and directly selectable; free text selection down to single words	2026-10-17
DEC_REVIEW_ON_RESULTS	Reviews happen on results, not only on source	2026-10-17
DEC_CLI_MASTER	The CLI is the master, with an openly documented file format	2026-10-17
DEC_DECIWA_FOLDER	All deciwa files in one .deciwa/ folder at the repository root or in a parent folder	2026-10-17
DEC_GIT_COMMITTED	.deciwa/ is committed to Git by default	2026-10-17
DEC_SKILLS	One or two agent skills for working with deciwa	2026-10-17
DEC_INTEGRATIONS	Integrations: VS Code, Chrome, Claude UI, desktop app	2026-10-17
DEC_FEEDBACK_CARD	Feedback card at the element is the default UI; side panel is the alternative; radial menu dropped	2026-10-17
DEC_DANWOS_TOKENS	deciwa uses the danwos colours and tokens	2026-10-17
DEC_THREE_MODES	Three ways of working that stay separate: feedback, quality rating, AI communication	2026-10-18
DEC_CARD_VERDICTS	The feedback card has four verdicts – approve, reject, approve & freeze, delete – plus a comment; a comment alone is a note; quality is rated with 0–5 stars	2026-10-19
DEC_FREEZE_BY_VERDICT	A freeze ends with a new verdict; there is no separate "lift freeze"	2026-10-19
DEC_DOCS_IN_REPO	Decisions, features and concepts live in the repository as Sphinx docs with Sphinx-Needs	2026-10-19
DEC_PACKAGES	deciwa is one repository of separate packages: core, server, CLI, UI and one per integration	2026-10-20

Purpose and scope

Decision: deciwa is a review and decision tool for everyone who works with docs and code DEC_PURPOSE

status: approved decided: 2026-10-17 reason: Daniel needs a simple way to review content and agree to statements (trigger: his own work in his knowledge base). alternatives: a decision log only; a tool for one group (developers, AI agents or management).

Decision: deciwa collects, evaluates and shows; it does not watch that decisions are kept DEC_NO_ENFORCING

status: approved decided: 2026-10-17 reason: Enforcing decisions is not possible; doing the work is the job of the AI or the developer. alternatives: a "watcher" that checks the implementation (dropped). refined by: PROP_CLI_CHECK

Decision: Three ways of working that stay separate: feedback, quality rating, AI communication DEC_THREE_MODES

status: approved decided: 2026-10-18 reason: Stars are a quick judgement independent of any verdict, to focus on weak areas later; AI questions are answered at the element by verdict or text. alternatives: stars as part of a verdict. refined by: PROP_ANNOTATION, PROP_LATEST_WINS, PROP_STATE_RULES

Feedback and decisions

Decision: The feedback card has four verdicts – approve, reject, approve & freeze, delete – plus a comment; a comment alone is a note; quality is rated with 0–5 stars DEC_CARD_VERDICTS

status: approved decided: 2026-10-19 reason: Seen in the prototype: seven three-line buttons were too big; what should change about a text is said better in the comment than with rephrase or more-details buttons; a note is just a comment without verdict; quality needs a clear scale with keys. alternatives: the seven buttons of the clickable prototype (approve, rephrase, more details, delete, freeze, reject, note) and 1–5 stars. refined by: Q_QUICK_ACTIONS

Decision: A freeze ends with a new verdict; there is no separate "lift freeze" DEC_FREEZE_BY_VERDICT

status: approved decided: 2026-10-19 reason: Approving an element again replaces one's own freeze anyway (latest verdict wins while the element is unchanged); a second way to lift it only confuses. alternatives: an explicit unfreeze command for humans only; deleting the freeze annotation.

Decision: Feedback verdicts plus quick actions for the AI DEC_VERDICTS

status: approved decided: 2026-10-17 reason: Approve, reject, note and the quick actions rephrase, more details and delete give the AI a complete instruction with one click. alternatives: free comments only. refined by: PROP_ANNOTATION

Decision: New verdict freeze DEC_FREEZE

status: approved decided: 2026-10-17 reason: Some wording must survive every edit; the AI must never change it, and deciwa raises an alarm if it changes anyway. alternatives: – refined by: PROP_ANNOTATION, PROP_CLI_CHECK, PROP_STATE_RULES

Decision: A decision is an approved statement, not an extra object DEC_DECISION_IS_APPROVAL

status: approved decided: 2026-10-17 reason: Decisions can then be mapped onto anything that is an element. alternatives: separate decision records in the source. refined by: PROP_STATE_RULES

Elements and formats

Decision: No markers in the source; elements come from the content DEC_NO_MARKERS

status: approved decided: 2026-10-17 reason: The source stays clean and every element stays documented (a Sphinx-Needs requirement, a heading, a Python function, an HTML container, a selected word). alternatives: [CHECK]-style markers or ids in the text. refined by: PROP_ADAPTER_API, PROP_RESOLVE, PROP_ROLLOUT_MIGRATE

Decision: Formats: text, HTML, Python, C, JS, TS, rST, Markdown, AsciiDoc DEC_FORMATS

status: approved decided: 2026-10-17 reason: Docs-as-code plus the results and code around it. alternatives: Markdown only. refined by: PROP_PYTHON_CORE

Decision: Format objects are highlighted on hover and directly selectable; free text selection down to single words DEC_HOVER_SELECT

status: approved decided: 2026-10-17 reason: Pointing must be as fast as looking. alternatives: line-based selection like a code review. refined by: PROP_ADAPTER_API, PROP_FREE_TEXT

Decision: Reviews happen on results, not only on source DEC_REVIEW_ON_RESULTS

status: approved decided: 2026-10-17 reason: Rendered docs and websites are what reviewers see; deciwa must not look like a pull-request code review. The source view shows the same element. alternatives: source-only review. refined by: PROP_PYTHON_CORE

Architecture and data

Decision: The CLI is the master, with an openly documented file format DEC_CLI_MASTER

status: approved decided: 2026-10-17 reason: One logic for all front ends; agents and integrations use the same commands and JSON. alternatives: a web app as the core. refined by: PROP_CLI_COMMANDS, PROP_CLI_JSON, PROP_LAYERS, PROP_PYTHON_CORE, PROP_SCHEMA

Decision: All deciwa files in one .deciwa/ folder at the repository root or in a parent folder DEC_DECIWA_FOLDER

status: approved decided: 2026-10-17 reason: The files must not get in the user's way; a parent folder covers several repositories or repositories that must stay untouched. alternatives: sidecar files next to each source. refined by: PROP_FILE_LAYOUT, PROP_ROLLOUT_LOCATION

Decision: .deciwa/ is committed to Git by default DEC_GIT_COMMITTED

status: approved decided: 2026-10-17 reason: Reviews are versioned together with the content. alternatives: git-ignored until a team decides. refined by: PROP_FILE_LAYOUT, PROP_ROLLOUT_LOCATION

Decision: One or two agent skills for working with deciwa DEC_SKILLS

status: approved decided: 2026-10-17 reason: Agents should pick up feedback and ask questions without extra prompting (deciwa-work, deciwa-ask). alternatives: – refined by: PROP_SKILLS_FORMAT

UI and integrations

Decision: Integrations: VS Code, Chrome, Claude UI, desktop app DEC_INTEGRATIONS

status: approved decided: 2026-10-17 reason: Reviews happen where people already work – editor, browser, chat; the desktop app covers people without an IDE. alternatives: –

Decision: Feedback card at the element is the default UI; side panel is the alternative; radial menu dropped DEC_FEEDBACK_CARD

status: approved decided: 2026-10-17 reason: Compared in the clickable prototype. alternatives: radial menu at the cursor.

Decision: deciwa uses the danwos colours and tokens DEC_DANWOS_TOKENS

status: approved decided: 2026-10-17 reason: Recognition across all danwos tools; the deciwa monster colours are only for pictures. alternatives: an own deciwa colour scheme.

Working on deciwa

Decision: deciwa is one repository of separate packages: core, server, CLI, UI and one per integration DEC_PACKAGES

status: approved decided: 2026-10-20 reason: The CLI and the server are reused by every integration; the logic stays in one place (core); integrations such as Sphinx, VS Code or Chrome stay independent of each other. alternatives: one package with everything (the first prototype, deciwa_proto). refined by: PROP_LAYERS

Decision: Decisions, features and concepts live in the repository as Sphinx docs with Sphinx-Needs DEC_DOCS_IN_REPO

status: approved decided: 2026-10-19 reason: Others develop in the repository too, and decisions act as requirements; Sphinx-Needs gives every decision an id, a status and links, and deciwa can later review its own docs. alternatives: decisions in Daniel's knowledge base only; MkDocs Material (plain text without ids or traceability).