diff --git a/docs/skills/general-dev-workflow.md b/docs/skills/general-dev-workflow.md index d9264fa..cdda4e2 100644 --- a/docs/skills/general-dev-workflow.md +++ b/docs/skills/general-dev-workflow.md @@ -85,11 +85,24 @@ Steps: - **Docker projects**: Run `docker compose --build` to verify all Docker images build successfully - Check build artifacts exist and are correct size (no suspiciously small binaries) -**Why build verification matters:** +**Docker container startup verification (required for Docker projects):** +- After successful build, run `docker compose up -d` to start all containers +- **Wait 10-15 seconds** for services to initialize (database migrations, seeding, etc.) +- Run `docker compose ps` and verify all containers have status **Up** (not Restarting or Exited) +- Run `docker logs ` for each container and verify: + - No errors or fatal exceptions in startup logs + - Services logged successful initialization (e.g., "startup complete", "listening for requests") + - Database migrations completed successfully (if applicable) + - Configuration loaded without errors +- **This is not optional for Docker changes** — a container that restarts means the change is incomplete +- If any container fails to start, the build is not successful until fixed + +**Why build AND startup verification matters:** - Catches missing dependencies, import errors, and configuration issues early -- Prevents "it works on my machine" problems during code review -- Docker builds especially must be verified as they catch missing project references and file copies -- A failed build blocks reviewers and CI/CD pipelines +- Docker builds catch missing project references and file copies, but don't catch runtime config problems +- Missing appsettings files, invalid environment variables, or database connection issues only show up at runtime +- A failed startup blocks entire services in production — this must be caught before code review +- A failed build blocks reviewers and CI/CD pipelines; a failed startup blocks production deployments **Write tests for your changes:** - Unit tests for individual functions/methods @@ -112,9 +125,9 @@ Steps: - Any manual testing notes - Known limitations or edge cases not yet tested -**Output**: Passing tests, code coverage report, test summary, successful build. +**Output**: Passing tests, code coverage report, test summary, successful build, containers running successfully (for Docker projects). -**Checkpoint**: Does the code compile without errors? Can you confidently say the code works? Are there any untested paths you're worried about? +**Checkpoint**: Does the code compile without errors? Do all Docker containers start and stay running (status: Up)? No errors in container logs? Can you confidently say the code works? Are there any untested paths you're worried about? --- @@ -197,7 +210,7 @@ Problem it solves / value it adds (2-3 sentences) **Keep phases focused.** Don't mix planning with implementation. Don't test in Phase 2. This separation helps catch problems early. -**Verify builds before review.** Always run a full build (`dotnet build` or `docker compose --build`) in Phase 4 before opening the PR. Build errors block reviewers and waste CI/CD time. If you're changing Dockerfiles or project dependencies, this is especially critical. +**Verify builds AND container startup before review.** Always run a full build (`dotnet build` or `docker compose --build`) in Phase 4 before opening the PR. **For Docker projects, also verify all containers start successfully** with `docker compose up -d` and check logs for errors. Build errors block reviewers; startup failures block deployments. Missing configuration files, invalid env vars, and DB connection issues only show at runtime. **Commit frequently.** Small commits are easier to review, easier to revert if needed, and easier to understand. Aim for 50-200 lines per commit.