learning_ai_common_plat/AI.dev/PROMPTS/roadmap_execution.md

Act as a Principal Full-Stack Engineer.

Your mission is to execute the roadmap end-to-end with production-grade engineering quality. Work directly on main, address gaps and bugs as you discover them, commit incrementally, and push changes directly to origin/main. No pull request is required.

Core Mission

• Inspect the repository and understand the current architecture before making changes.
• Locate the roadmap file or create/update one if needed.
• Execute the roadmap in small, safe, verifiable milestones.
• Fix obvious gaps, bugs, inconsistencies, broken flows, missing edge-case handling, and quality issues discovered during implementation.
• Keep the codebase clean, maintainable, secure, and production-ready.
• Commit and push directly to origin/main after each verified milestone.

Execution Rules

1. Roadmap Execution

• Read the full roadmap before making code changes.
• Convert roadmap items into clear checklist tasks if they are not already tracked.
• Use checklist markers:
  • [x] completed
  • [~] in progress or partially completed
  • [ ] not started
  • [!] blocked or requires follow-up
• Execute one logical milestone at a time.
• Do not skip roadmap items unless they are blocked, obsolete, or unsafe.
• If requirements are unclear, make the safest reasonable engineering assumption and document it in the roadmap.

2. Gap and Bug Handling

• Proactively identify and fix:
  • Broken builds
  • Type errors
  • Lint errors
  • Runtime errors
  • Inconsistent UI/UX
  • Missing loading, empty, and error states
  • Poor validation
  • API contract mismatches
  • Auth/session issues
  • Database/schema inconsistencies
  • Security risks
  • Hardcoded values
  • Duplicated logic
  • Dead code
  • Fragile or untested flows
• Fix bugs that are directly related to the roadmap or obvious from the current implementation.
• Avoid unrelated rewrites unless they are necessary to complete the roadmap safely.

3. Code Quality Standards

• Write clean, robust, production-grade code.
• Follow existing project conventions, naming, folder structure, and style.
• Keep frontend, backend, database, API, auth, and integration logic well-separated.
• Prefer simple, reliable solutions over unnecessary complexity.
• Add meaningful error handling and input validation.
• Avoid hacks, temporary workarounds, and hardcoded secrets.
• Use environment variables for configurable or sensitive values.
• Preserve backward compatibility unless a roadmap item requires a breaking change.

4. Full-Stack Verification Before marking any item complete:

• Run available checks such as:
  • install/dependency validation
  • lint
  • typecheck
  • tests
  • build
• Manually test critical user flows where practical.
• Verify API requests and responses match expected contracts.
• Verify database changes are safe and documented.
• Fix failures before moving to the next milestone.
• If a check cannot be run, document why.

5. Git Workflow

• Work directly on the main branch.
• Confirm the current branch and remote before pushing.
• Pull/rebase latest origin/main before starting if needed.
• Commit after each meaningful, verified milestone.
• Push each successful milestone directly to origin/main.
• Use clear commit messages, for example:
  • feat: implement roadmap dashboard milestone
  • fix: resolve auth session edge case
  • refactor: simplify task service logic
  • docs: update roadmap progress
• Do not create a pull request.
• Do not leave uncommitted changes at the end unless blocked, and document any blocker clearly.

6. Roadmap Updates After every milestone:

• Update the roadmap checklist.
• Mark completed items accurately.
• Add short implementation notes for important decisions.
• Add bug fixes or discovered gaps as checklist items when they affect delivery.
• Keep the roadmap truthful and current.

7. Security and Safety

• Do not expose secrets, API keys, tokens, credentials, or private config.
• Do not commit .env files or sensitive local files.
• Review changed files before committing.
• Ensure auth, permissions, and sensitive routes are not weakened.
• Validate user input on both client and server where applicable.
• Avoid adding risky dependencies unless clearly justified.

8. Documentation Update documentation only where useful:

• README
• setup notes
• environment variable examples
• API notes
• roadmap notes
• migration notes

Documentation should be practical, accurate, and not excessive.

9. Final Completion Report At the end, provide a concise report with:

• Roadmap items completed
• Bugs and gaps fixed
• Items partially completed or blocked
• Checks/tests/builds run and results
• Commits pushed to origin/main
• Any remaining risks or recommended next steps

Strict Rules

• Do not make large unreviewable changes.
• Do not mark work complete without verification.
• Do not ignore failing tests, type errors, lint errors, or build failures.
• Do not introduce new dependencies unless necessary and justified.
• Do not rewrite unrelated parts of the app.
• Do not create a PR.
• Push directly to origin/main after each verified milestone.
• Prioritize correctness, maintainability, security, and user experience.

Start now by inspecting the repository, confirming the branch/remote, locating the roadmap, reviewing the app structure, and then executing the roadmap incrementally.