Prepare useful development data before first preview

[raghubetina]

Completed bounded scope — 2026-09-23

The shared planning/continuation guidance and source evaluations are merged in #86 at 4c4dab13309478983433fc4805955e7dd2c769d5. The retained evidence distinguishes fresh source exercises from the four local generated-app previews. The generated README companion, Service #770, is merged at 8ccb9a94ec8511c38b683e6b7daf41e449a2a70a. Its retained receipt separates the original four local application previews from the final integration comparison and current-head CI; the four README/seed outputs are unchanged.

Guide alignment is delivered. Drawing Board #51 and #52 are merged; the latter is d290c6baf052e4088f34b7938afb2457351fd122, with exact-head CI and Opus 5.5 review. The testing guide now includes sample-or-empty planning, visible records and demo login, public disposable credentials, conditional development seeding, current archive paths and RSpec, and generated-Compose browser checks. The published guide bytes match the reviewed proposal; historical trial results are unchanged. All amended instructions are source-compatible with the released Service/CLI/plugin 0.4.0. A local Docker recreation passed 105 application and 42 browser examples plus explicit cleanup after failure; it is not a new Codespaces or colleague trial.

Fresh installed-client/repository-only discovery remains under Service #712, broader unaided journey qualification under #504, and provider-specific attachment/private preview under #729/#730. Those separate boundaries remain open; this issue's guidance, bounded evaluations, README companion and guide delivery are complete.

The distinct post-Compilation continuation from finding 39 is complete through #89 at c873e96ad2743f062e23be7981a5da9b674a4676. Its retained evidence shows an agent extending ordinary development seeds, three repeat runs without duplicates, both existing password fingerprints preserved, and an isolated production-configuration zero-demo control. The second account's empty state is DB-only because its password had deliberately changed earlier; no nonempty all-environment lookup dataset was exercised. The evaluated Skill source remains 4c4dab; this evidence-only merge changes no packaged guidance.

The separately authorized September 22 release records deployed Service output, CLI/plugin 0.4.0 and catalog promotion. Those delivery records retain their own source boundaries; these source/evaluation results do not establish fresh installed-client discovery or a new colleague trial. The September 23 guide update changes documentation only; no additional software deployment or package publication accompanies it.

---

Parent: Ben/Jelani feedback decision tracker #43. Related: #84 — real examples and artifacts during the interview, primarily for modeling, with optional appropriate reuse as sample data.

Original task status (superseded by the implementation status above): direction accepted on 2026-09-22; implementation and fresh-agent qualification were pending.

Prepare useful development data before the first preview

Priority and current-source refresh — 2026-09-22

The current primary journey is local root Compilation; Codespaces remains a fallback. Apply the same dataset/preview standard to both without requiring a Codespace. CLI/plugin 0.3.0 are published; current Skills source also contains the newer local-first workflow. The September 22 assisted local trial explicitly requested sample books, so it does not satisfy this issue's evaluation where the initial user prompt never asks for data.

The owner explicitly moved seed/sample data and the first-preview experience ahead of the recent smaller audit questions and accepted the focused Skill/preview fix below. This issue owns that work; it does not reopen the existing seed emitter or require a comprehensive Skill overhaul. Include the small conditional README improvement under Service #712.

Current source was rechecked, without a fresh generated-app runtime trial:

• Service main is 03163b80e2fac0ac820a18ba1bde9a4427413e9d, consuming Core d3e646e7018419f65b6a29a82edce09d3ce5a86e. The seed-readability packet is now integrated through #758; the older research statement that #744 was still open is historical. #420 retains the actual remaining Position/RichText assignments and the separate seed-lint remainder.
• Skills main is 2d6edee825e6d40fdb0786e1d6e21b346a0d7f8d. Its main Skill/modeling guide ask for semantic read-back including material data, and its format reference documents optional development_data, but these files still establish no default connected-dataset proposal or first-preview population checkpoint.
• Core setup still calls bin/rails db:prepare; the environment dispatcher keeps samples in db/seeds/development.rb. The current generated README template does not describe the actual emitted demo login. Those findings support using the existing seed mechanism and improving preparation/discovery; they do not establish a new setup defect.
• The earlier four-of-five empty-Plan finding remains historical inspected-trial evidence. Do not relabel it as a fresh current-main experiment.

The accepted outcome is a useful, populated first preview: representative related records and relevant states for the intended flow, plus an accessible development login where supported, with an explicit empty-data choice. Do not turn this into a comprehensive Skill overhaul, a new seed framework, or a requirement for the user to approve every sample row individually.

Original research packet — 2026-09-19, accepted as refined below on 2026-09-22. Original finding 5; coordinated with finding 11 in the linked development-login research.

Owner: firstdraft/skills, under Skills #20, with Drawing Board guide alignment and a bounded generated README addition under Service #712. Service #504 owns broader qualification and #420 owns the existing emitter and its remaining coverage. Do not duplicate the seed-rendering work integrated through #758.

Report and attribution

Ben found the more complex Movie Tracker difficult to explore before he separately asked for sample records and a usable login. He proposed automatic sample data and hydration before first launch. Jelani observed that his second trial included data, possibly because his prompt contained examples, and asked whether this should become an interview question. Ben's report, Jelani's report.

The September 13 audit inspected five baseline Plans: four omitted application.development_data and emitted an empty development seed file; Habit trial 2 contained nine authored records. Its fresh setup and repeated seed run retained 2 Goals, 4 Habits, and 3 HabitLogs. This is evidence of an authoring omission in those inputs, not absence of a seed generator. The old observation is not a fresh five-app qualification on today's main.

Historical source snapshot — 2026-09-19

• Service b079cd2b74c024f44819893f85eddbb981c6bca4 still emits reviewed, dependency-ordered development records in db/seeds/development.rb. The living data model distinguishes disposable development records from reference data needed in every environment. Explicit record assignments are typed literals/references, not arbitrary Ruby or Faker calls.
• PR #744, head c82bddfb84612dcb3506a6737d9edef5503244ff, simplifies ordinary records to find_or_create_by!; its reported qualification covers 14 Oscar records, reruns, Account password handling and State Machine outcomes. It remains open at this inspection. That work does not cause planning agents to propose records in the first place.
• Skills main a001a24cc47b5f2c421012f6f5cb38750e14e443 asks for a semantic summary including material data, but neither the main Skill nor modeling guide establishes a first-preview dataset checkpoint.
• Drawing Board main 3e4ba3d3b62de78642be2c46975ed2454c74130f and guide revision c779f473f0482d057ef79e79944d86d43ce072e9 tell users to run setup and exercise CRUD; they do not explicitly verify reviewed data is present before preview.
• Core d3e646e7018419f65b6a29a82edce09d3ce5a86e runs bin/rails db:prepare in bin/setup. Rails 8.1.3.1's DatabaseTasks.prepare_all loads seeds when it initializes a seeds-enabled database; it does not re-seed an already initialized database on every setup. A later data change requires an ordinary explicit seed command. A reset is destructive and is not a routine way to hide missing data.

Rationale and prior art

The current separation is deliberate: the Plan preserves approved application meaning, and the Compiler produces that meaning deterministically. Inventing records in the Compiler would make an empty Plan mean something different and could invent Accounts or relationships with no user review.

Rails provides db:seed and recommends repeatable seed code; current thoughtbot guidance separates all-environment reference data from development exploration data. Suspenders gives developers a dedicated development-seeding path. These support a populated development experience without a new dataset manager or test-factory dependency. They do not prescribe one universal number of records. Rails seed conventions, Rails preparation behavior, thoughtbot guidance, Suspenders.

Alternatives considered

1. Default planning proposal, approved with the Plan — recommended. Offer a small, useful connected dataset for the first intended flow. Include sign-in data only when the app has supported Account behavior. The ordinary Plan review makes the proposal visible, including an explicit empty-data choice when appropriate. This adds a little authoring work and may enlarge the Plan, but the data is reproducible and reviewed.
2. Always let the implementation agent add data after Compilation. Ordinary Rails can express rich scenarios quickly and relative dates flexibly. It adds an early source-edit task and cannot prove a populated untouched baseline; keep this as a fallback for meaning outside current data support.
3. Have the Compiler invent data automatically. Reject: it bypasses semantic review and conflates generation with product design.

Do not force a large record census or a separate approval turn for every record. Propose enough variety to exercise the chosen flow, meaningful relationships and relevant states. Include an empty state intentionally when useful. Avoid real personal data. Historical date literals should be labeled as historical; do not promise an authored literal will remain “today,” or invent an unsupported runtime-value grammar to keep samples fresh.

Accepted implementation scope — 2026-09-22

1. Planning: normally propose a small, realistic, connected application.development_data dataset that demonstrates the intended first flow and relevant states. Include a development Account where supported and useful. Make this part of the existing Plan proposal/read-back and approval; a user can choose an empty start, and individual rows do not need separate approval turns.
2. First preview: run ordinary setup, explicitly load the development seeds when needed, and verify actual visible records, relationships, and the intended demo sign-in before announcing a useful preview. Do not assume that a successful Compile, a seed file, or a successful setup command proves the populated experience. Disclose actual omissions/gaps; retain outside-grammar follow-up needs in the existing notes workflow.
3. Continuation: preserve the existing development-only boundary for disposable samples/accounts. Keep app-required reference data distinct. A follow-up that adds UI examples should normally extend db/seeds/development.rb; it should not move demo accounts into all-environment seeds or reset an existing password merely to make documentation match.
4. Discoverability: add a short conditional generated README section with the actual emitted development login route, initial disposable credentials, and relevant setup/sample-data commands. Emit it only for a realized seeded Account with a known password; explain that a changed local password remains the user's chosen password. Clearly distinguish these intentionally public local-demo values from actual owner/provider/production credentials. Keep Skill, Drawing Board, and guide wording consistent with that distinction.
5. Evaluation: use a realistic authoring request that never asks for sample data, follow it through Compilation/setup to visible sample records and usable login, and cover an explicit empty-data choice and an Account-free app. Preserve existing repeat-seed and password behavior evidence; add only the checks needed to prove this user journey.

The FP already distinguishes Entity reference_data from application development_data. The immediate sample-data fix is guidance, verification, and the small README addition. Automatic Rails reference-data emission and remaining unsupported assignments are separate Compiler coverage; this issue must not claim them as implemented.

#84 adds the owner's related request to ask early about actual CSVs, spreadsheets, photos, and other artifacts, principally to improve modeling. If a derived sample is appropriate, carry its agreed reuse/transformation into this workflow. Source material supplied only to explain the domain is not automatically seed data or repository content.

Bounded acceptance

• An authoring scenario with no sample-data request produces a visible proposal, not silent additions; a user choosing no data keeps an empty dataset.
• Reuse Movie v2 and Habit trial 2 as realistic comparisons; include one Account-free Plan and one supported Account Plan.
• Verify the selected records survive import and reviewed gap handling. Omitted/unsupported records are disclosed rather than replaced with fabricated ones.
• Fresh development setup produces the expected relationships and useful screen content. A repeat seed run behaves according to #744's accepted lookup semantics, without duplicate records or resetting an existing password.
• If existing setup skipped seeding, explain and use bin/rails db:seed when appropriate. Never reset the tester's database automatically.
• Match Skill, Drawing Board README and testing guide instructions. Record exact source/release versions before claiming a new colleague trial is ready.

This scope uses the existing Plan data shapes and conventional seed mechanism. It does not introduce a scenario registry, seeding gem, Compiler-invented data, or production demo mode. Issue creation records the accepted work; no implementation, publication, deployment, or release is claimed.

[raghubetina]

Parent: Ben/Jelani feedback decision tracker #43. Research recommendations remain pending unless a prior decision is explicitly identified.

Preserve development-only sample data during continuation

Research packet — 2026-09-19. Original finding 39. This corrects an unsafe proposed exemplar; it is not an unresolved Compiler seed architecture decision.

Suggested owner: firstdraft/skills continuation guidance, with one concise link from owner documentation if needed. Keep #420 and #712 as related owners. A new seed-management subsystem or protected generated region is out of scope.

Report and actual code

Ben's Movie v3 design task explicitly requested diverse samples for a live UI review. Its continuation commit 7fb2bc03e3c9499017ce519034f1b6a32f4b88ee added useful data but replaced the environment dispatcher in db/seeds.rb with 161 lines of unguarded sample records, including verified Accounts. The password helper writes a deliberately shared throwaway password hash through SQL on every seed run. No production exposure was observed; this is a source-verified continuation regression, not evidence that the Compiler emitted production demo accounts.

The generated baseline and current Core d3e646e7 deliberately load the seed file for Rails.env. Current Core's development file is an empty commented starting point. The Compiler fills that file for reviewed supported data. The existing split is small, readable Rails application code.

Why the boundary exists

Reference/lookup rows can be necessary in every environment; disposable UI records and known demo logins are not. Rails runs db/seeds.rb through ordinary database setup, including production initialization. Consequently, moving local examples to that file changes more than file organization.

Current thoughtbot guidance and Suspenders make the same environmental distinction, though they use a dedicated development seeder/task rather than First Draft's environment file. The relevant convention is separation of development examples from all-environment required data, not the exact path or a custom framework. thoughtbot seed guidance, Suspenders seed convention, Rails seed behavior.

Options

• Small continuation note plus a targeted check when editing seeds — recommended. Tell the agent to extend existing db/seeds/development.rb, preserve the environment distinction, and verify repeated loading. The owner may deliberately replace the arrangement later; nothing is a permanent First Draft region.
• New gem, guarded seed DSL or generator-owned seed contract. Not justified by this example; it adds machinery to a straightforward source edit and repeats the audit's overengineering problem.
• Copy the successful UI commit's seed implementation wholesale. Reject as the exemplar: preserve its useful dataset/design result, but correct its environment and password-update behavior.

One owner question

Should the shared continuation guidance explicitly tell agents to preserve the existing development-only seed boundary when adding preview data, with a focused check whenever they change that boundary?

Acceptance

• An evaluated “populate the UI with sample data” continuation edits the existing development seed file and leaves all-environment startup free of demo users and sample rows.
• Preserve legitimate reference/lookup data intended in every environment; do not forbid ordinary production seeding.
• A repeat development seed run has the intended application semantics. Reuse #744's password preservation instead of overwriting an existing user's password through raw SQL.
• If demonstrating the Movie v3 dataset, independently check fresh development counts, repeat counts/relationships and an isolated production-configuration seed path. Do not run this against a retained or real production database.
• Put compiler guarantees in Compiler/Core qualification, and application behavior tests where useful. Do not ship a synthetic test that permanently demands First Draft's file layout.

Existing source is already correct at the environmental boundary. The proposal is handoff guidance and an evaluation, not another seed implementation.