# Kwark method

> How Kwark goes from a filmmaker's problem to a shipped screen, the tests every decision passes, and where each step is written down.

Source: https://kwark.space/designSystem/method

## What this section is

Kwark is a story workspace built by a founder working alone with AI agents. There is no product team to catch a wrong turn in a meeting, so the method has to be written down well enough that a person or an agent who arrives cold can follow it and reach the same answer the founder would.

The method has one purpose, taken from the mission in `docs/ux/mission-and-principles.md`: help people who want to write feel calm, begin writing and keep writing, then take the same work into production. Every step below exists to protect that, and every step leaves a file behind.

## The loop

A change a person will see goes through six steps, in this order. Bug fixes and polish use the short version at the end of this page.

1. **Is it needed?** Name the person, the situation and the problem in one sentence, from how they actually work. "A competitor has it" is not a reason. Say what happens to the person if Kwark does nothing.
2. **Their journey.** Walk the whole path: where they come from, what they see at each step, what can go wrong, how they get back to writing.
3. **Show the shape.** A wireframe or a built mock-up at phone size first, then desktop, with empty, loading, error and offline states. Count what competes for attention above the fold.
4. **Agreement.** The founder confirms the journey and the shape. Open decisions are asked, never silently defaulted; obvious ones are decided and stated as the builder's call.
5. **Build** in small steps that each ship safely, with tests, through the review ladder.
6. **Record.** A decision record in `docs/ux/decisions/`, every new dot, badge, count or colour in the element register, and the UI map updated if a component was added.

The loop is not a waterfall. Step 3 often sends you back to step 1: drawing the call sheet issue panel is what showed that "Issued" was a field nothing ever set.

## The tests every screen passes

These come from `docs/ux/how-we-decide.md`. A screen that fails one is changed or dropped, whoever asked for it.

| Test | The question |
|---|---|
| Calm | Looking at it as a nervous first-time writer, does anything count, grade, warn, nag or ask for attention it has not earned? |
| Five seconds | Can someone say what this screen is for and what to do next in five seconds? Is the thing they came for in the first 200px on a phone? |
| Meaning | Can we say what every element is for, down to the last dot? |
| Remove it | What evidence would make us remove this? It is written in the record. |
| Work is safe | If this fails, loses connection or is interrupted halfway, what happens to the writing? |
| Everyone | Phone, tablet, laptop; keyboard only; screen reader; slow or no network; a script in Tamil; a user in another country. |
| Honest copy | Read every word aloud to a nervous writer. No hype, no shouting, no blame, no jargon. |

And the empathy checklist, used in every review: who is this for and what were they doing a minute ago; what are they afraid of right now; what is the smallest thing that helps; what are we making them look at that is not their work; what can they not undo.

## The standing rules

Some answers are settled and are not reopened by a new feature. Each has a decision record and a page here.

- **Kwark is a safe, private place** (Decision 0001). No contests, leaderboards, public counts or comparing badges. Anything social belongs on Bekwarky, a separate site.
- **Kwark never judges the script** (Decision 0002). No AI scores, coverage or verdicts, and no percentage that rates the writer.
- **Structure is always optional** (Decision 0003) and **structure, not teaching** (Decision 0004). See [Structure, not teaching](https://kwark.space/designSystem/method/structure-not-teaching.md).
- **Paper and digital as one act** (Decision 0005). See [Specs and handoff](https://kwark.space/designSystem/method/specs-and-handoff.md).
- **Competitors are the floor** (Decision 0006). See [Competitors are the floor](https://kwark.space/designSystem/method/competitors-are-the-floor.md).
- **Their work is never at risk** (principle 12). A feature that can lose work is not shipped.
- **The free tier is a design constraint.** About 50 people on Firebase's free allowance. See [Review and quality](https://kwark.space/designSystem/method/review-and-quality.md).

> **For agents:** Before you build anything a person sees in Kwark, read `docs/ux/mission-and-principles.md`, `docs/ux/how-we-decide.md` and the decision records your change touches. If your change contradicts a record, stop and say which one; do not quietly override it.

## Who does what

| Role | Does | Never |
|---|---|---|
| Founder | Agrees journeys and shapes; decides open questions; says yes to every push to main and every rules deploy | Is asked a question that has an obvious default |
| Builder (person or agent) | Finds the need, walks the journey, shows the shape, builds, writes the record | Pushes, deploys rules or picks an expensive-to-reverse option without a yes |
| Supervisors (separate agents, review-only) | Role simulation, UI, UX, database, security, founder judgement, engineer handoff | Edit the code they review, or dismiss a finding without a written reason |

## Where it is written down

| File | What it holds |
|---|---|
| `docs/ux/mission-and-principles.md` | The mission, the state Kwark protects, twelve principles with a test each |
| `docs/ux/how-we-decide.md` | The order of work, the tests, the empathy checklist, the dot rule |
| `docs/ux/decisions/` | One record per decision, numbered. See [Decision records](https://kwark.space/designSystem/method/decision-records.md) |
| `docs/ux/element-register.md` | Every dot, badge, count, colour and edge, with what it means |
| `docs/ux/definition-of-done.md` | The gate and the review ladder |
| `docs/ux/HANDOFF.md` | State for the next person or agent; updated every time work stops |
| `docs/ux/audit/` | Audits and supervisor reviews, one file each |
| `~/AIContext/log.md` | The cross-tool handoff log; an entry every time an agent stops |

## Short version for bug fixes and polish

Say what the person experienced. Fix the cause, not the symptom. Add a test that fails without the fix. If the fix changes what a person sees, add a dated line to the relevant decision record's history.

## The method, step by step

- [UX before build](https://kwark.space/designSystem/method/ux-before-build.md): On any feature that spans more than one screen, walk the person's journey and agree its shape by showing it, before a line of code is written.
- [Discovery](https://kwark.space/designSystem/method/discovery.md): How Kwark decides what is worth building for a person: who it is for, the real job, the assumptions that could be wrong, and the smallest test, without inventing research it does not have.
- [Competitors are the floor](https://kwark.space/designSystem/method/competitors-are-the-floor.md): Parity with other writing and production tools is the minimum. Every plan leads with what none of them does, and a competitor review is how Kwark finds both.
- [Structure, not teaching](https://kwark.space/designSystem/method/structure-not-teaching.md): Every field in Kwark feeds a real artefact a person can use. Kwark never coaches, quizzes or explains film theory, and every piece of structure can be switched off.
- [Specs and handoff](https://kwark.space/designSystem/method/specs-and-handoff.md): How a Kwark feature is specified so that anyone can build it, phone first, with every state and every word written, and with the paper artefact and the digital one designed as one act.
- [Decision records](https://kwark.space/designSystem/method/decision-records.md): Every decision a person can see or feel gets one numbered record that says the problem, the options, why this one, and what would make us remove it.
- [Review and quality](https://kwark.space/designSystem/method/review-and-quality.md): What "done" means for a Kwark change: built from the system, looked at in screenshots, reviewed by separate supervisors, tested, inside the free-tier budget, then shipped to main one feature at a time.
- [Product skills](https://kwark.space/designSystem/method/product-skills.md): The product-management and design skills Kwark uses, what each is for, when it is the right tool, and how to run it with an AI agent so the answer stays true to Kwark's rules.

## AI readiness test

**Task:** The founder says "add a word-count leaderboard for co-writers". Plan the work.

**Give the agent:** This page, Decision 0001, Decision 0002, docs/ux/how-we-decide.md.

**Constraint:** Follow the loop; do not write code.

**A reliable answer:**
- Stops at step 1 and names the conflict with Decision 0001 (no leaderboards or public counts)
- Asks what problem the co-writers have, in one sentence
- Offers a private alternative only if a real need survives (for example a rhythm only the writer sees)
- Points social features to Bekwarky
