system-sentence

name

system-sentence

description

Produce a structural system sentence (what a software system *is* as an object that exists over time) from a feature-framed or flow-framed description, generative enough that 3–5 distinct states fall out of its nouns and verbs. Use this whenever a user is starting state-first design work on a software product, has described a system in feature terms ("helps the user…", "lets people…") or flow terms ("first X, then Y…"), needs to anchor a state audit on an existing product, or is otherwise trying to nail down what a stateful software system fundamentally is before listing states or designing screens. The first step in the Stateful method. Skip for systems that are not stateful (landing pages, marketing surfaces, static documents) and as a prompt-optimisation step for a generative model.

System Sentence

Produces a structural system sentence: what the system is as an object that exists over time, not what it does for the user. Initial states should be derivable directly from the sentence.

Output discipline

No preamble, no narration of the procedure, no restating the method or the user's input. Deliver the output format below plus only what needs the user's decision. Terse but complete: the sentence, the structural terms, the derived states, and the why-it-works lines are the whole output.

Procedure

Before starting. Read STATEFUL.md from the working directory if it exists. If a ## System sentence section is already populated, ask the user whether to replace it or proceed without writing back before continuing.

1. Read the user's description. Classify it as feature-framed, flow-framed, or structural. Name the classification back to the user.

2. Check the altitude. A useful sentence lives at feature or surface scale, not whole-app scale (see PRACTICE's Scope section). If the user described a whole product ("our shopping app", "the platform"), ask them to pick a single feature or surface to describe now. If they insist on the whole app, warn that the resulting sentence will abstract past the point of usefulness, and recommend either narrowing or shifting to a cross-cutting inventory (recurring conditions like unauthenticated, offline, subscription expired) instead of a sentence.

3. Elicit the structural raw material. The initial description rarely contains what a generative sentence needs; get it before drafting, in a single round of questions. Ask only what the description has not already answered (skip aggressively; asking what is already stated reads as not listening). Use the platform's interactive question facility if one exists (multiple-choice with a free-text escape); otherwise ask as a plain numbered list. The five probes:

   • Time. What exists when nobody is looking? What windows, deadlines, expiries, or schedules govern it?
   • Lifecycle. What gets created, and what can happen to it before it ends: resolved, cancelled, expired, superseded, abandoned?
   • Channels. Does the process leave the product and come back: email, push, another device, another person?
   • Completion differences. What may have changed between start and finish: device, session, data, permissions, elapsed time?
   • Surfaces. Where does the system show itself besides the primary screen?

   Offer candidate answers where you can infer them; confirming is cheaper than composing. The answers are raw material for the sentence, not the sentence; none and unknown are acceptable answers and constrain the draft honestly.

4. Draft a structural sentence from the description plus the elicited raw material. Describe what the system is as an object that exists over time, not what it does for the user. Aim for 15–30 words.

5. Extract the structural terms from your draft: the verbs and time-bearing nouns. List them explicitly. If there are fewer than three, rewrite. The list is part of the output; the state-list skill uses it as the coverage anchor (every term must generate at least one state).

6. Derive three to five initial states from the sentence and show them to the user. This is the agent-runnable half of the test for a useful sentence.

7. If the states are thin or tautological, iterate on the sentence, not on the states.

8. Present for confirmation and stop. Show the user the sentence, one or two lines on why it works (which structural terms carry the load and what kind of states each generates), and the derived states. Ask them to confirm or adjust. Do not proceed to the state list and do not write to STATEFUL.md until they have. If they adjust, re-run steps 5 to 7 on the adjusted sentence and present again.

9. After confirmation, return the confirmed sentence, the structural terms, the derived states, the two earlier drafts (feature, flow) for reference, and a recommendation that the user run the colleague check from PRACTICE: read the sentence to someone unfamiliar with the product and confirm they can describe at least three distinct conditions without leading questions. The colleague check is human-only and not performed by this skill.

Working memory. Only after the user confirms: update STATEFUL.md in the working directory, replacing the contents of the ## System sentence section with the confirmed sentence. Beneath the sentence, record the elicited raw material as one-line bullets (time, lifecycle, channels, completion differences, surfaces); the state-list skill uses them as elicitation seeds. If the file does not exist, create it with this section. Stamp Last updated: <date> by system-sentence.

Inputs required

• The user's initial description of the system, feature, or product.
• Answers to the raw-material probes; the skill elicits these itself in step 3.
• Optional: the user's intended audience for the system (affects the structural framing only when the audience introduces a genuine structural property, e.g. multi-tenant).

Output format

Final sentence:
<one sentence, 15-30 words, structural framing>

Why it works:
<one or two lines: which structural terms carry the load, what kind of states they generate>

Structural terms:
<the verbs and time-bearing nouns, listed; these anchor the state list's coverage check>

Initial states derived:
- <state 1>
- <state 2>
- <state 3>
(up to 5)

Confirm or adjust? <wait for the user before the state list or any write to STATEFUL.md>

Earlier drafts (for reference):
- Feature-framed: <sentence>
- Flow-framed: <sentence>

Common failure modes

• Feature-framing leaks in. The sentence contains "helps" or "allows" or "so that". Rewrite without those verbs.
• Flow-framing leaks in. The sentence lists steps in sequence ("first X, then Y, then Z"). Rewrite as a description of the object, not the sequence.
• Sentence at app altitude. The sentence describes a whole product ("a bookstore-and-reader app is a catalogue with a purchase path and a reading surface"). It generates almost no useful states because everything abstracts to categories. Descend to a feature or surface (checkout, reader, library) and write a sentence for that. Handle cross-cutting conditions (auth, offline, entitlement) as a shared inventory referenced by feature-level maps.
• Over-specification. The sentence lists states rather than generating them. If the sentence contains a list, rewrite.
• Aesthetic compression. The sentence reads well but yields no states. Trade elegance for generativity.
• Derivation faked. The states listed are not actually derivable from the sentence. If the test fails, the sentence fails.
• Proceeding on an unconfirmed sentence. The sentence anchors everything downstream. Listing states from a sentence the user has not confirmed risks fifty states of rework; the confirmation costs one message.
• Interrogating instead of drafting. More than one round of questions, or questions the description already answers, turns the skill into a form. One round, five probes at most, then draft.

Example

User input: "We're building a medication tracker that helps users remember to take their pills on time and tracks whether they took them."

Elicitation round (only the probes the description left open):

• Time: dose windows recur daily, with an overdue threshold before a dose counts as missed.
• Lifecycle: prescriptions change, pause, and get discontinued mid-course.
• Channels: push reminders; doses can be marked from a watch or widget without opening the app.
• Completion differences: doses get marked late, from another device, or not at all.
• Surfaces: widget, watch, lock screen; user adds a printable clinician export.

Skill output:

Final sentence:
A medication tracker is a time-indexed obligation ledger that reconciles scheduled doses against taken doses across varying adherence, delay, substitution, and prescription-change conditions, rendered on surfaces the user visits intermittently.

Why it works:
"Time-indexed" and "reconciles" generate the dose lifecycle (pending, due, overdue, taken late); "visits intermittently" forces the interruption and surface states a reminder-app framing would miss.

Structural terms:
time-indexed, obligation ledger, reconciles, scheduled doses, taken doses, adherence, delay, substitution, prescription-change, rendered on surfaces, visits intermittently

Initial states derived:
- Scheduled dose pending (window not yet open)
- Scheduled dose due (window open, not yet taken)
- Scheduled dose overdue (window open, missed threshold)
- Dose taken on time
- Dose taken late (reconciliation required)

Confirm or adjust? I will not start the state list until you have.

Earlier drafts (for reference):
- Feature-framed: "A medication tracker helps users remember to take their pills on time and tracks whether they took them."
- Flow-framed: "A medication tracker is an app where the user sets up a schedule, receives reminders, and records each dose as taken or missed."

Recommended next step: read the final sentence to a colleague unfamiliar with the product and confirm they can describe at least three distinct conditions the system occupies, without leading questions. If they cannot, return to step 3.