Goal-Calibration/ai/backend_prompt_template.md

Entity Creation Prompt Template

Follow the existing patterns in this codebase to:

• create a new entity called [EntityName].

Requirements:

• The entity encapsulates [one or more Entities]
• Include [any other fields]

Process (TDD - Test Driven Development):

1. Write a test first
2. Run the test to confirm it fails
3. Implement the code to make the test pass
4. Run the test to confirm it passes
5. Repeat for each new behavior

Code patterns to follow:

• First, explore the codebase to understand existing entity patterns
• Look at similar entities (e.g. Node, Text, etc.) for reference
• Entities: constructor with properties, getters
• DTOs: simple data containers for creation
• Repositories: interfaces that define data access
  • Do not write unit tests for concrete repository implementations (e.g., Doctrine/persistence-backed). They are exercised by e2e tests. Use cases are tested with fake repositories.
• Use cases: business logic with Request objects
  • When throwing exceptions, add @throws docblock
• Fakes: in-memory implementations for testing
  • Look at tests/Fakes/ for examples
  • Find/lookup methods must return a new instance of the entity, not the stored reference
• Tests: follow existing patterns in tests/Unit/[Entity]/UseCases/
  • In setUp, only use fake repositories for entities under test - construct dependency objects directly with new (e.g., new Text(....)) instead of creating them through their fake repositories
• Lines should not exceed 80 columns, but should use up to 80 columns when possible - do not split lines unnecessarily
• Imports: always put use statements at the top of the file, never use inline imports (e.g., \App\Foo\Bar::class)
• Variable names: use explicit, descriptive names - never single-letter or abbreviated variables (e.g., use $sponsorship not $s, $event not $e)
• Never use em-dashes (—) in code, comments, commit messages, or any written output. Use a regular hyphen (-), a colon, or rephrase with parentheses instead.

Git commit style:

• Subject: present tense, imperative mood (add, create, test, fix)
• Subject: lowercase, short (3-6 words)
• Match subject patterns found in git history
• Add a body when the change needs explanation beyond the subject - e.g., why the change was made, non-obvious tradeoffs, or notable implementation details. Skip the body for trivial/self-evident commits.
• Separate subject and body with a blank line; wrap body at ~72 columns

Git commits:

• Tests should be committed first, before implementation
• Group related changes together in a single commit (e.g., a new class plus its registration, or a getter plus the property it exposes). Avoid mixing unrelated concerns in one commit.
• Keep commits small and focused - prefer many small commits over few large ones, but don't artificially split a single logical change across multiple commits
• Commits are for reviewing and documenting the development of code
• Don't wait to commit - commit as you go
• Run php-cs-fixer fix on worked on directories before committing

Branch naming:

• Use kebab-case (e.g., presenting-track, agenda-slots)
• Use descriptive feature names
• Examples: "presenting-track", "agenda-slots", "confirm-application"
• Or use type/description: "feature/presenting-track", "fix/bug-name"
• NEVER work directly on master/main - always create and work on a branch

Do not push anything. Make commits as you go.