Skip to content

DEVELOPMENT_SCENARIO_GUIDE.md

Latest commit

 

History

History
338 lines (210 loc) · 8.96 KB

DEVELOPMENT_SCENARIO_GUIDE.md

File metadata and controls

338 lines (210 loc) · 8.96 KB
Raw

Devine Development Scenario Guide

Devine development work starts from documented sprint cards and ends with a verified running app.

Table of Contents

Scenario 1: Set up a new checkout

Use this when you have just cloned the repository.

  1. Install dependencies.
bun install --frozen-lockfile
  1. Create local environment configuration.
cp .env.example .env.local

  1. Fill .env.local with local values. Use .env.example and docs/technical-specs/11-environment-configuration.md as the source of truth.

  2. Run migrations and local seed data.

bun run db:migrate
bun run db:seed:dev
  1. Start the app.
bun run dev

  1. Open http://localhost:3000 and confirm the landing page renders.

  2. Confirm health.

curl "$NEXT_PUBLIC_APP_URL/api/health"
  1. Run the full verification gate.
bun run complete-check

Scenario 2: Pick up a sprint card

Use this for any planned feature, fix, or scaffold-completion task.

  1. Open docs/TASK_BREAKDOWN.md.

  2. Choose one card. Note its card ID, owner role, acceptance criteria, and linked docs.

  3. Read the acceptance criteria under docs/business/.

  4. Read the linked API specs, module specs, architecture specs, and security docs.

  5. Inspect the current implementation in app/, lib/, components/, and tests/.

  6. Decide whether the task is backend, frontend, tech-lead contract, or wiring work.

  7. Keep scope to the card. Do not add future sprint behavior unless the card requires it.

  8. Before handoff, run the checks that match the change and then the full gate.

bun run complete-check

Scenario 3: Implement a backend card

Use this for persistence, domain logic, route handlers, server actions, auth, daily.dev, scoring, quest, power-up, demo, share, reset, or health behavior.

  1. Start from the card in docs/TASK_BREAKDOWN.md.

  2. Read the relevant API contract in docs/api-specs/ if the work touches a route or server action.

  3. Read the relevant module spec in docs/technical-specs/05-module-definitions.md.

  4. Add or update slice tests in features/<slice>/tests/.

  5. Implement product behavior under the relevant features/<slice>/ layer.

  6. Keep direct database access in lib/db/.

  7. Keep route handlers and server actions thin. They should validate input, authorize the caller, call public feature APIs, and map results to responses.

  8. Run focused checks.

bun run type-check
bun run test
  1. If the change affects formatting or lint rules, run:
bun run lint
bun run format
  1. Run the full gate before handoff.
bun run complete-check
  1. Update the relevant docs if contracts, environment variables, architecture, or verification commands changed.

Scenario 4: Implement a frontend card

Use this for landing, auth, dashboard, settings, share pages, components, loading states, empty states, error states, or visual polish.

  1. Start from the card in docs/TASK_BREAKDOWN.md.

  2. Read the relevant route, UI, and acceptance criteria docs.

  3. Inspect the current page or component under app/ and components/.

  4. Add or update Playwright coverage in tests/e2e/ for user-visible golden paths.

  5. Implement the UI with existing component and styling patterns.

  6. Start the running app.

bun run dev

  1. Manually verify the changed route in the browser. Include golden path, empty state, error state, and nearby navigation where applicable.

  2. Run focused checks.

bun run type-check
bun run test:e2e
  1. Run the full gate before handoff.
bun run complete-check
  1. Update docs when route behavior, UI flow, or verification instructions changed.

Scenario 5: Implement an API contract card

Use this for Tech Lead cards that specify contracts before implementation work.

  1. Open the relevant sprint section in docs/TASK_BREAKDOWN.md.

  2. Read the cited acceptance criteria under docs/business/.

  3. Read related module and integration specs under docs/technical-specs/.

  4. Add or update the matching contract document under docs/api-specs/.

  5. Define request shapes, response shapes, status codes, validation rules, authorization rules, privacy constraints, failure envelopes, and test expectations.

  6. Cross-link the API spec to the technical source documents instead of restating long architecture sections.

  7. Run documentation index checks if the changed docs affect generated or linked indexes.

python scripts/check_index.py
  1. If code changed, run the relevant code checks and then:
bun run complete-check

Scenario 6: Wire a feature end-to-end

Use this for wiring cards where backend and frontend work must be proven together.

  1. Confirm all prerequisite backend and frontend cards are complete or present in the branch.

  2. Start the app.

bun run dev
  1. Prepare local state.
bun run db:migrate
bun run db:seed:dev

  1. Execute the acceptance path in the browser from the user's point of view.

  2. Confirm server behavior with route checks where useful.

curl "$NEXT_PUBLIC_APP_URL/api/health"

  1. Add or update Playwright coverage for the full path.

  2. Verify privacy-sensitive output manually. Public share pages must show only documented public projection fields.

  3. Run the full gate.

bun run complete-check

Scenario 7: Reset local state

Use this when local data needs to return to a known development seed.

  1. Confirm .env.local is pointed at a disposable local database or safe development database.

  2. Confirm reset is enabled only outside production.

APP_ENV=development
ENABLE_RESET_API=true
RESET_STATE_SECRET=replace-with-local-reset-secret
  1. Start the app.
bun run dev
  1. Call the reset endpoint.
curl -X POST "$NEXT_PUBLIC_APP_URL/api/admin/reset-state" \
  -H "Authorization: Bearer $RESET_STATE_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"seed":"dev"}'

  1. Restart the development server.

  2. Verify health.

curl "$NEXT_PUBLIC_APP_URL/api/health"

If the reset API is unavailable, use the project migration and seed runners against a disposable local database.

bun run db:migrate
bun run db:seed:dev

Do not use ad hoc destructive SQL against shared or production-like data.

Scenario 8: Review a PR

Use this when reviewing another contributor's change.

  1. Read the PR summary and identify the sprint card or acceptance criteria it claims to satisfy.

  2. Read docs/CODE_REVIEW_CHECKLIST.md and docs/CODING_STANDARD.md.

  3. Confirm the change stays inside the card scope.

  4. Check that domain logic is in lib/, route handlers are thin, and reusable UI components remain presentation-only.

  5. Check security and privacy boundaries:

    • daily.dev tokens are server-only.
    • private user data is owner-scoped.
    • public share snapshots are allowlisted.
    • reset endpoints are absent or unreachable in production.

  6. Run or verify the full gate.

bun run complete-check
  1. For UI changes, run the app and verify the affected route in a browser.
bun run dev
  1. Request changes for correctness, security, privacy, contract drift, missing tests, or broken acceptance criteria.

Scenario 9: Prepare a release update

Use this when a change is going to main and Vercel will deploy it.

  1. Read docs/DEPLOYMENT_PLAN.md.

  2. Run the full local gate.

bun run complete-check

  1. If schema changes are included, create a Neon branch or snapshot before applying migrations.

  2. Run migrations against the intended target database only after confirming DATABASE_URL.

bun run db:migrate

  1. Merge or push to main through the project's approved GitHub flow.

  2. Confirm Vercel deploys the selected commit.

  3. Verify hosted health.

curl "$NEXT_PUBLIC_APP_URL/api/health"
  1. Inspect Vercel logs and Neon status for runtime or database errors.

Rollback and database recovery procedures live in docs/DEPLOYMENT_PLAN.md.