From ba97889151dec45edf4d39d4d219731c741e5c23 Mon Sep 17 00:00:00 2001 From: Raghu Betina Date: Sun, 4 Oct 2026 19:33:08 -0500 Subject: [PATCH] Use First Draft as one tool for the user's app On 2026-10-04 the owner decided that First Draft is a tool in the agent's belt: plan, plan and Compile, or neither, whichever serves the user's goal. The Skill assumed every request was an app First Draft could build and told the user what it could not build only after the first push. An idea whose core is real-time sensors or a game loop got an interview for records it did not need. references/interview.md now starts from the user's goal. Before every interview the agent takes a quick look at how others build similar apps, to choose better questions and defaults. When feasibility is in question, such as sensors, APIs, or real-time behavior, it researches thoroughly and reports what it found with sources. As soon as it is clear, it says which of four ways First Draft helps: plan and Compile, plan and Compile the backbone while native Swift or Kotlin carries the core, plan only, or not at all, naming the right tool. A fitting app gets no fit talk. The modeling guide keeps three lists in implementation-notes.md and the read-back: what First Draft builds, what is built otherwise, and feasibility findings and open questions. The description now triggers on a request to make or plan an app or game. SKILL.md routes in one line and shrinks from 20,332 to 20,313 bytes by tightening the schema, read-back, and download paragraphs. Rehearsals ran in fresh Claude Code 2.1.286 sessions on Opus 5.5 (claude -p with only this worktree's plugin loaded): - Race-car coaching: three web searches, then an opening turn with sourced findings (1 Hz phone GPS, 10-25 Hz external receivers, Garmin Catalyst, RaceChrono and Harry's LapTimer) that said First Draft builds the backbone, not the sensor advice. After the answers it pushed a backbone Plan to Production (driver Account, cars, tracks, sessions, laps; iPhone and Android requested): valid, two gaps, both phone clients not generated because every page needs sign-in. It named that consequence and asked the user to choose. - First-person shooter: with an app-only description the Skill did not trigger and the agent began building a game itself. With "app or game" it triggered, named Godot, Unity, Unreal, and Three.js, offered First Draft later for accounts or leaderboards, and pushed no Plan. - Family network: the first run opened with "fits this tool well", so the fitting case now says not to mention fit; the rerun had none. With research always on, a third run made two searches (FamilyAlbum and Tinybeans, Instagram clones in Rails), noted that only invited people see posts and that follows add little for one family, and asked the usual three questions without fit talk or a push. - The Rails-maintenance and CSV-analysis controls did not trigger it. Five structural eval cases cover the fit decisions. The version, its CHANGELOG entry, and the tarball digest stay with the 0.8.4 release. --- CHANGELOG.md | 17 +++++ evals/create-full-stack-app/cases.json | 68 ++++++++++++++++++- .../candidate-interview-protocol.md | 5 +- skills/create-full-stack-app/SKILL.md | 34 +++++----- .../references/interview.md | 59 +++++++++++++--- .../references/modeling-guide.md | 43 ++++++++---- test/repository.test.mjs | 16 ++--- 7 files changed, 187 insertions(+), 55 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cfcd2e4..82e0588 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,6 +29,23 @@ Entries are newest first. Keep their headings stable. Publish material correctio new entries so readers who advanced their checkpoint see them. Entries explain what changed, why, when it applies, and any useful small example or verification; they need not reproduce commit logs. +## Pending for 0.8.4 + +This section is not a dated entry. The plugin 0.8.4 release moves it into that release's dated entry. + +- The Skill treats First Draft as one tool for your app instead of assuming it can build whatever you describe. + Before the interview the agent takes a quick look at how others build similar apps and uses what it finds to + choose better questions and defaults. When feasibility is in question, such as phone sensors, outside data, + store rules, or real-time behavior, it researches thoroughly whether the idea is possible and tells you what it + found with sources. As soon as it is clear, it says how First Draft helps: + plan and Compile the whole app; plan and Compile the backbone, such as accounts, sessions, and lists, while the + core, such as real-time sensor advice, is built separately in native Swift or Kotlin; plan only, when you will + build in another stack; or not at all, as for a first-person shooter, where it names a game engine and offers + First Draft later for accounts, leaderboards, or a website. An app of records and people, such as a family photo + feed, gets no talk about fit and starts the interview as before. `implementation-notes.md` and the read-back keep three lists: what First + Draft builds, what is built otherwise, and feasibility findings and open questions. The Skill's description now + starts from your goal, so it triggers when you ask for help making or planning an app or game. + ## 2026-10-03: An interview that asks your level first **Skills — released in plugin 0.8.3.** The Skill's interview now follows one order. The agent clarifies your idea, diff --git a/evals/create-full-stack-app/cases.json b/evals/create-full-stack-app/cases.json index c626833..6597c47 100644 --- a/evals/create-full-stack-app/cases.json +++ b/evals/create-full-stack-app/cases.json @@ -39,7 +39,7 @@ "Prioritizes whether one inventory record represents a uniquely identified object, a quantity of interchangeable goods, or both because that answer changes the Entity and Field model.", "Keeps its first reply to a small coherent batch of questions chosen for their effect on the first-release graph, access model, or requested clients instead of walking the entire ambiguity matrix.", "Leaves consequential unanswered areas open without silently deciding them; it may name deferred examples when that helps but does not satisfy an arbitrary minimum count.", - "Keeps this interview evaluation local and does not run plan push, plan status, plan compile, or make a network request before the user answers the consequential opening questions.", + "Keeps this interview evaluation local and does not run plan push, plan status, plan compile, or make a First Draft service request before the user answers the consequential opening questions.", "Does not claim that one complete candidate Foundation Plan is ready before the user has answered the consequential opening questions." ], "artifacts": [ @@ -178,7 +178,7 @@ "Asks once whether it should make the technical decisions for the user, explain them as it goes, or ask about them.", "Asks no more than three questions in this opening turn and leaves details such as list fields, deletion, and appearance for later turns.", "Does not ask about hosting.", - "Runs no plan push, plan status, or plan compile and makes no network request in this opening turn." + "Runs no plan push, plan status, or plan compile and makes no First Draft service request in this opening turn; a brief web search for similar apps is expected." ] }, { @@ -218,6 +218,70 @@ "Does not run plan compile." ] }, + { + "id": "fit-partial-opening-race-coaching", + "should_trigger": true, + "prompt": "Help me build an app for hobbyist race car drivers that gives them real-time advice while they drive, using the phone's sensors.", + "expectations": [ + "Before replying, uses its web search tools to check whether the idea is possible, such as phone GPS and motion-sensor rates and accuracy and what the platforms allow while driving, and how existing apps such as lap timers and driver-coaching tools are built.", + "Opens the reply with a few lines on what it found, with sources.", + "Says in this opening turn, in plain words, that First Draft can build the backbone, such as drivers, cars, tracks, sessions, and laps, but not the real-time sensor reading and advice, which is the core of the idea.", + "Names what builds that part and where, such as native Swift or Kotlin added to the generated iPhone or Android project, and says those projects are Hotwire Native shells around the web app.", + "Then asks the opening questions, at most three, including once whether it should make the technical decisions, explain them as it goes, or ask about them.", + "Runs no plan push, plan status, or plan compile and makes no First Draft service request in this opening turn." + ] + }, + { + "id": "fit-partial-backbone-plan-race-coaching", + "should_trigger": true, + "prompt": "Help me build an app for hobbyist race car drivers that gives them real-time advice while they drive, using the phone's sensors. You already researched it, with sources, and said First Draft can build the backbone while the real-time sensor advice is built separately in native code. My answers to your opening questions: drivers sign up and see only their own sessions, I want an iPhone app, I have nothing to share, and make the technical decisions for me.", + "expectations": [ + "Writes a rough Plan for the backbone only, such as a driver Account with cars, tracks, sessions, and laps, and does not model the real-time sensor reading or advice as if First Draft generated it.", + "Runs plan push and plan status --wait and reads the matching analysis before asking detailed questions.", + "Tells the user in a few plain lines what First Draft will build, what it will not build yet, and what is built otherwise, including that the generated phone apps show only public pages and have no sign-in, so coaching code that saves a driver's laps needs its own sign-in.", + "Keeps private access and the requested iPhone app in the Plan instead of making pages public or dropping the client to avoid gaps.", + "Writes implementation-notes.md with three lists: what First Draft builds; what is built otherwise, naming the real-time sensor and advice work and where it goes; and feasibility findings and open questions, with sources.", + "Does not run plan compile." + ] + }, + { + "id": "fit-none-first-person-shooter", + "should_trigger": true, + "prompt": "Help me build a first person shooter.", + "expectations": [ + "Says plainly that First Draft isn't the right tool for the game itself, because the core is a real-time game loop, 3D rendering, and input.", + "Names what is, such as a game engine like Unity, Unreal, or Godot, and offers to help with that.", + "Mentions that First Draft could later build a part it fits, such as accounts, leaderboards, or a website, if the user wants it.", + "Does not ask the First Draft level question or start the First Draft interview.", + "Runs no plan init, plan push, plan status, or plan compile and creates no .firstdraft directory." + ] + }, + { + "id": "fit-full-family-photo-network", + "should_trigger": true, + "prompt": "Help me build a social network for just my family. It should work and look like Instagram so that it's familiar. This is our first message; do not contact First Draft yet.", + "expectations": [ + "Before replying, takes a brief look with its web search tools, a few searches, at how similar family photo-sharing apps are built: common features, patterns, and pitfalls.", + "Does not make any statement about whether First Draft fits, not even that the idea fits; it may mention one or two useful findings, such as a feature most family photo apps share.", + "Restates the idea in a sentence and proposes a name.", + "Invites materials such as screenshots or an app the user likes, and says none is required.", + "Asks once whether it should make the technical decisions for the user, explain them as it goes, or ask about them.", + "Asks no more than three questions in this opening turn and leaves photo support and phone-app consequences for the reality check after the user answers.", + "Runs no plan push, plan status, or plan compile and makes no First Draft service request in this opening turn." + ] + }, + { + "id": "fit-plan-only-other-stack", + "should_trigger": true, + "prompt": "I'm going to build a volunteer shift app for our food bank myself in Django, but I'd like help designing the data first. Coordinators create shifts, and volunteers sign up for them. You already asked your opening questions; my answers: volunteers and coordinators both sign in, I have nothing to share, and make the technical decisions for me.", + "expectations": [ + "Says plainly that First Draft will help with planning only: the Foundation Plan and its analysis help design the data, and its generated Rails app will not be used.", + "Writes a Plan for the data model, such as volunteers, coordinators, shifts, and signups, then runs plan push and plan status --wait and uses the matching analysis to check the model.", + "Does not dwell on what the Rails Compiler would or would not generate, and asks the remaining data questions one at a time.", + "Writes implementation-notes.md with three lists, naming the Django build under what is built otherwise.", + "Never runs plan compile and does not offer to Compile." + ] + }, { "id": "meaning-asked-implementation-by-level", "should_trigger": true, diff --git a/evals/create-full-stack-app/references/candidate-interview-protocol.md b/evals/create-full-stack-app/references/candidate-interview-protocol.md index 1bd2dd4..d9f12f3 100644 --- a/evals/create-full-stack-app/references/candidate-interview-protocol.md +++ b/evals/create-full-stack-app/references/candidate-interview-protocol.md @@ -101,8 +101,9 @@ and deferred questions can be revisited after diagnostics or further dialogue. Before the first Compile that could start direct retained work or reach Publication, reread the exact staged Plan and give a plain-language semantic summary first: application scope; Entities and their material Fields, relationships, -rules, behavior, and data; surfaces, access, and clients; material assumptions, delegated choices, exclusions, and -open questions. Then group the gaps by what the user will notice. End with a short technical block: the Plan path +rules, behavior, and data; surfaces, access, and clients; material assumptions, delegated choices, and exclusions. +Then group the gaps by what the user will notice, then list what is built outside First Draft and the feasibility +findings and open questions. End with a short technical block: the Plan path and SHA-256, the matching valid AnalysisRun's GapSet digest and record count, and the file holding every ordered record. Explain that service gaps were skipped before semantic analysis, target gaps were not fully realized, and `valid` applies only to the admitted graph. State the selected completion mode: direct output creates only a diff --git a/skills/create-full-stack-app/SKILL.md b/skills/create-full-stack-app/SKILL.md index 5174743..93d4706 100644 --- a/skills/create-full-stack-app/SKILL.md +++ b/skills/create-full-stack-app/SKILL.md @@ -1,14 +1,14 @@ --- name: "create-full-stack-app" -description: "Experimental and in development: Authors and revises First Draft Foundation Plans, submits exact bytes, and requests bounded Rails/iPhone/Android Compile. Preserves identity, state, and provenance. Web Accounts, Policies, protected Scaffolds, and required enums are bounded; arbitrary apps, deployment, iPad, notifications, and broader clients are unavailable." +description: "Use when someone asks for help making or planning an app or game, even one First Draft may not fit. Experimental: researches whether the idea is possible and how similar things are built, then uses First Draft where it helps: Foundation Plans, analysis, and bounded Rails/iPhone/Android Compile for records, people, permissions, lists, and forms. Says early when First Draft won't cover the core, and what will." license: "MIT" --- # Create a Full-Stack App with First Draft -Author and review a coherent Foundation Plan, then Compile through the First Draft service into the current local -folder. Run and develop the generated app locally. A Codespace is an optional fallback; GitHub publication and native -preview are optional follow-ups. Compilation does not deploy. +Use First Draft where it helps the user's app: author and review a Foundation Plan, then Compile through the First +Draft service into the current local folder. Run and develop the generated app locally; a Codespace, GitHub +publication, and native preview are optional. Compilation does not deploy. ## Preserve implementation requirements @@ -58,11 +58,10 @@ For CLI work: read [ambiguous mutations](references/diagnostics-and-recovery.md#ambiguous-mutations) only when the named error requires it. -The bundled [JSON Schema](references/foundation-plan-0.23.schema.json) is machine-readable validator input, not prose. -Use a compatible JSON Schema 2020-12 command named by the user, exposed by the project, or found through a -straightforward check of existing local commands. Pass only its path; never read it end to end. Do not install -dependencies or add validation/build plumbing solely for this workflow. Otherwise rely on First Draft exact-byte -diagnostics and say local schema validation was not performed. +The bundled [JSON Schema](references/foundation-plan-0.23.schema.json) is validator input, not prose: pass only its +path to a compatible JSON Schema 2020-12 command the user names, the project exposes, or a quick check of existing +local commands finds; never read it end to end. Install nothing and add no validation plumbing for this. Otherwise +rely on First Draft exact-byte diagnostics and say local schema validation was not performed. ## Verify the local capability @@ -126,7 +125,8 @@ reinitialize. Inspect private state only for a recovery check explicitly named i ## Interview and author incrementally -Start when the user asks for help making an app or invokes `/create-full-stack-app`, and follow the +Start when the user asks for help making an app or invokes `/create-full-stack-app`. First research the idea and +[decide how First Draft helps](references/interview.md#start-from-the-users-goal), then follow the [interview flow](references/interview.md#interview-flow). Clarify the idea; ask for materials and read them before asking more; ask once, "Should I make the technical decisions for you, explain them as I go, or ask you about them?" Then ask the product questions that shape the data model, most important first and one decision per turn, @@ -196,10 +196,10 @@ valid status so the complete GapSet can be reviewed. `plan compile` later repeat Before the first `plan compile`, complete the modeling guide's [candidate reconciliation](references/modeling-guide.md#prepare-the-pre-compile-semantic-read-back), then reread the exact current -`.firstdraft/foundation-plan.json`. Follow that section's order: a plain-language summary, then the gaps grouped by -what the user will notice, then a short technical block with the Plan path and SHA-256 and the matching valid run's -`gap_set_sha256`. Write every ordered GapSet record with all its fields to planning-root `gaps-readback.md` and -name that file instead of pasting the records into the chat. Use only that attached +`.firstdraft/foundation-plan.json`. Follow that section's order: a plain-language summary first and a short +technical block last, with the Plan path and SHA-256 and the matching valid run's `gap_set_sha256`. Write every +ordered GapSet record with all its fields to planning-root `gaps-readback.md` and name that file instead of pasting +the records into the chat. Use only that attached digest: the CLI validates it against the attached GapSet; never substitute a fixture, historical, or another Project's digest. Use current-folder output by default. Select an absent `--output ` for a requested destination, an ineligible root, or model-only originals when root output was not @@ -283,9 +283,9 @@ firstdraft_cli() { sh "/scripts/firstdraft.sh" "$@"; } firstdraft_cli compilation download --output ``` -Download reads one succeeded Compilation, verifies retained provenance, transport, manifest, paths, modes, and file -digests, then installs atomically. It never starts or polls work. `--output .` uses the same current-root transaction -and preconditions as direct Compile; preserve every other existing destination. +Download reads one succeeded Compilation, verifies it, and installs atomically; it never starts or polls work. +`--output .` uses the same current-root transaction and preconditions as direct Compile; preserve every other +existing destination. ## Recover from failures diff --git a/skills/create-full-stack-app/references/interview.md b/skills/create-full-stack-app/references/interview.md index c56becb..117286b 100644 --- a/skills/create-full-stack-app/references/interview.md +++ b/skills/create-full-stack-app/references/interview.md @@ -5,12 +5,49 @@ to model each answer. The Skill's read-back, approval, and Compile rules are unc ## Contents +- [Start from the user's goal](#start-from-the-users-goal) - [Interview flow](#interview-flow) - [Meaning and implementation](#meaning-and-implementation) - [See what First Draft emits](#see-what-first-draft-emits) - [Coverage checklist](#coverage-checklist) - [After-Compile checklist](#after-compile-checklist) +## Start from the user's goal + +First Draft is one tool for the user's goal. Use it where it helps: to plan and Compile, to plan only, or not at +all. Decide which before the opening turn. + +**Research first, always.** Before the opening turn, take a quick look with your web search tools, a few searches, +at how others build similar apps: common features, patterns, and pitfalls. Use what you find to choose better +questions and defaults. Research thoroughly only when feasibility is in question, because the idea depends on a +device capability, outside data or APIs, store or platform rules, or real-time behavior. Then find out whether it +is possible (device sensors and their limits, APIs, store rules, and whether the data exists) and how others build +it (existing apps, their stacks, and their known limits), and start the opening turn with a few lines on what you +found, with sources. + +**Decide how First Draft helps.** When it won't cover the core of the idea, say so as soon as that is clear, which +is usually the opening turn: + +- **Plan and Compile:** the core is records, people, permissions, lists, and forms, such as a book club or a + private family photo feed. Do not mention fit, not even that the idea fits. You may mention one or two useful + findings, such as "Most family photo apps also let you…"; then start the interview. +- **Plan and Compile the backbone; build the rest separately:** the core is continuous computation or a device + capability, such as real-time sensors, a game loop, live audio or video, on-device machine learning, + offline-first sync, Bluetooth or other hardware, or background location. First Draft builds the accounts, + records, and pages around it. Name what comes after and where, such as native Swift or Kotlin in the generated + iPhone and Android projects. Those projects are Hotwire Native shells around the web app: device features are + code added there, and the shells show only public pages, with no sign-in. +- **Plan only:** the user will build in another stack, or won't use the generated code. The Foundation Plan and its + analysis still help design the data model: push it and use the analysis to check the model, skip the reality + check about what First Draft generates, give the read-back, and do not Compile. +- **Not at all:** First Draft doesn't help with the core, and the core is the app, such as a first-person shooter. + Say First Draft isn't the right tool and name what is, such as a game engine like Unity, Unreal, or Godot. Say + First Draft could later build a part it fits, such as accounts, leaderboards, or a website, if the user wants. + Do not initialize or push a Plan unless the user asks for that part. + +Then continue with whichever applies; the interview below covers the First Draft part. Keep the +[three lists](modeling-guide.md#retain-implementation-requirements) in the notes and the read-back. + ## Interview flow Start when the user asks for help making an app, such as "help me make an app for my book club", or invokes @@ -24,7 +61,7 @@ Start when the user asks for help making an app, such as "help me make an app fo 3. **Ask the user's level once:** "Should I make the technical decisions for you, explain them as I go, or ask you about them?" Do not ask it again; the user may change it at any time. -Steps 1 to 3 are the opening turn, with at most three questions. +Steps 1 to 3 are the opening turn, after the research and any fit, with at most three questions. 4. **Ask product questions** that decide the data model, most important first: which records exist and what one record is, who can see and do what, and whether they want iPhone or Android apps. After the opening turn, ask @@ -35,20 +72,20 @@ Steps 1 to 3 are the opening turn, with at most three questions. database, and that a paid option is planned. 5. **Give an early reality check.** As soon as the opening answers settle the main records, tell the user this takes a few minutes, then write a rough Plan, push it, and read its analysis. Keep the rough Plan small: the main - records and their key Fields, any Account, who can see what, and requested phone apps. Tell the user in a few - plain lines what First Draft will build and what it will not build yet, for example "Photos aren't generated - yet, so posts start caption-only; I'll add photo upload in Rails after" or "iPhone and Android apps show only - pages anyone can see, and have no sign-in; a private app works in the phone's browser". Then let the analysis - steer the remaining questions: ask about consequences the user can choose between, not about gaps they cannot - change. Keep private access and requested phone apps in the Plan. Report each gap as the analysis gives it, - even when its reason names no cause or contradicts these references; the deployed First Draft may not generate - it yet. Do not trim the Plan or push trial or example Plans to find a cause: each push replaces the Project's - current Plan, and a defensible variant is still a trial. + records and their key Fields, any Account, who can see what, and requested phone apps; for a backbone, only the + part First Draft builds. Tell the user in a few plain lines what First Draft will build and what it will not + build yet, for example "Photos aren't generated yet, so posts start caption-only; I'll add photo upload in Rails + after" or "iPhone and Android apps show only pages anyone can see, and have no sign-in; a private app works in + the phone's browser". Then let the analysis steer the remaining questions: ask about consequences the user can + choose between, not about gaps they cannot change. Keep private access and requested phone apps in the Plan. + Report each gap as the analysis gives it, even when its reason names no cause or contradicts these references; + the deployed First Draft may not generate it yet. Do not trim the Plan or push trial or example Plans to find a + cause: each push replaces the Project's current Plan, and a defensible variant is still a trial. 6. **Ask implementation choices last**, following the user's level and [meaning and implementation](#meaning-and-implementation). 7. **Walk the [coverage checklist](#coverage-checklist)** silently, and write the [after-Compile checklist](#after-compile-checklist) into the implementation notes. -8. **Read back and approve** as the Skill describes, then Compile. +8. **Read back and approve** as the Skill describes, then Compile. For plan only, give the read-back and stop. At any point the user may say "make the rest of the decisions for me". Stop asking. Choose your recommendation for every remaining item, including product meaning, and mark each one delegated. Then walk the checklist and give the diff --git a/skills/create-full-stack-app/references/modeling-guide.md b/skills/create-full-stack-app/references/modeling-guide.md index d9d8a14..203ef79 100644 --- a/skills/create-full-stack-app/references/modeling-guide.md +++ b/skills/create-full-stack-app/references/modeling-guide.md @@ -44,8 +44,9 @@ Plan as answers arrive. Prioritize answers that change the graph, access model, When modeling a collection, distinguish one uniquely identified object, a quantity of interchangeable goods, and a mixed product that needs both meanings. Do not collapse that branch into only individual-versus-group wording. In the opening turn, ask only about intended product meaning, materials, and the user's level, and name deferred -product areas; give the reality check about target support after the user answers, unless feasibility was itself -part of the request. Do not promote a common use case into an assumption. When target support matters, know the +product areas; give the reality check about target support after the user answers. Whether First Draft covers the +core of the idea is [fit](interview.md#start-from-the-users-goal), not target support: say it in the opening turn +when research shows it. Do not promote a common use case into an assumption. When target support matters, know the desired access before describing the current Account, Policy, Web, and native boundaries. Keep one candidate Plan: do not maintain a parallel flattened or capability-friendly shape merely so one version can Compile. @@ -148,11 +149,19 @@ extend `db/seeds/development.rb`; keep demo Accounts out of all-environment seed ## Retain implementation requirements -Maintain `implementation-notes.md` at the planning workspace root as the conversation establishes behavior that the -Plan cannot express. Write the product requirement, relevant Entities or interactions, useful rationale, and a few -acceptance examples. Separate agreed requirements from unresolved questions and proposals. Keep it concise and -revise it when the user's decisions change; it is not a transcript, task database, or second structured Plan. -Add the applicable [after-Compile checklist](interview.md#after-compile-checklist) under `## After Compile`. +Maintain `implementation-notes.md` at the planning workspace root as the conversation establishes what the Plan +cannot express. Keep it in three lists, then the after-Compile steps: + +- `## What First Draft builds`: a line or two naming the Plan and its gaps file; do not copy them. +- `## What is built otherwise`: each agreed requirement outside the Plan, with relevant Entities or interactions, + useful rationale, and a few acceptance examples; and each part of the idea that First Draft does not cover, with + where it will be built, such as native Swift in the generated `ios/` project. +- `## Feasibility findings and open questions`: what research found and its known limits, with source links, and + each unresolved question or proposal. +- `## After Compile`: the applicable [after-Compile checklist](interview.md#after-compile-checklist). + +Keep it concise and revise it when the user's decisions change; it is not a transcript, task database, or second +structured Plan. For example, an agreed CSV import may need to preview all row errors before saving anything and save a valid file as one transaction. Record examples such as "one invalid row leaves all records unchanged" and "a valid file saves @@ -403,19 +412,23 @@ a confirmed product decision, or a demonstrated diagnostic. Write it for a reader who is not technical, in this order: -1. A plain-language summary: what the app is for and who uses it; each kind of record and its material Fields, - with each relationship as a "must" or "may" sentence; rules, sign-up and access, and clients; what each main - list shows; a few of the proposed sample records and any the gaps will drop; and delegated choices, - assumptions, exclusions, open questions, and outstanding implementation notes with how the selected output - mode carries them forward. For an Account, say plainly whether people can sign in right after signing up or - confirm their email first, as the [Accounts reference](foundation-plan-023.md#accounts-and-policies) describes. +1. What First Draft builds, as a plain-language summary: what the app is for and who uses it; each kind of record + and its material Fields, with each relationship as a "must" or "may" sentence; rules, sign-up and access, and + clients; what each main list shows; a few of the proposed sample records and any the gaps will drop; and + delegated choices, assumptions, and exclusions. For an Account, say plainly whether people can sign in right + after signing up or confirm their email first, as the + [Accounts reference](foundation-plan-023.md#accounts-and-policies) describes. 2. What is not generated yet. Group the gaps by what the user will notice, lead with that effect, and say what the app does instead, for example "Photos aren't generated yet; posts are caption-only" or "Like and follower counts aren't generated yet". Use one line per group rather than one per record, and say which groups you plan to build in Rails after Compile. -3. A short technical block: the Plan path and SHA-256; the matching valid run's `gap_set_sha256` and record count; +3. What is built otherwise: outstanding implementation notes and any part of the idea outside First Draft, each + with where it will be built, and how the selected output mode carries the notes forward. +4. Feasibility findings and open questions, with sources for what research found. Leave out a list with nothing + in it. +5. A short technical block: the Plan path and SHA-256; the matching valid run's `gap_set_sha256` and record count; that service gaps were skipped before semantic analysis, target gaps were analyzed but not fully realized, and - `valid` covers only the admitted graph; the selected output mode; and the gaps file. + `valid` covers only the admitted graph; the selected output mode, or plan only; and the gaps file. Before giving the read-back, write planning-root `gaps-readback.md`: the Plan SHA-256, the `gap_set_sha256`, and every ordered GapSet record with its classification, code, kind, status, location, reason, consequence, and cause diff --git a/test/repository.test.mjs b/test/repository.test.mjs index 290e3d9..88ad571 100644 --- a/test/repository.test.mjs +++ b/test/repository.test.mjs @@ -2949,16 +2949,16 @@ async function checkSkill(skillName) { assert(metadata.description.length > 0); assert(metadata.description.length <= 1024); if (skillName === "create-full-stack-app") { - assert.match(metadata.description, /^Experimental and in development:/); - assert(metadata.description.includes("First Draft Foundation Plan")); + // Discovery starts from the user's goal and must not claim First Draft builds any app it is asked for. + assert.match(metadata.description, /^Use when someone asks for help making or planning an app or game,/); for (const fragment of [ - "Authors and revises First Draft Foundation Plans", - "submits exact bytes", - "Web Accounts, Policies, protected Scaffolds, and required enums are bounded", - "arbitrary apps", - "broader clients are unavailable", + "Experimental", + "researches whether the idea is possible", + "uses First Draft where it helps", + "Foundation Plans, analysis, and bounded Rails/iPhone/Android Compile", + "won't cover the core", ]) { - assert(metadata.description.includes(fragment)); + assert(metadata.description.includes(fragment), `description must include "${fragment}"`); } assert.doesNotMatch(metadata.description, /Accounts[^.;]*are not available/); assert(source.includes("## Load references only when needed"));