Engineering — How We Work

• Branches live less than a day before being merged back to trunk.
• Only fast-forward merges to trunk; squash short-lived branches before merging.
• Rebase your branch against current trunk to keep it fresh — never merge trunk back into a feature branch.
• No hotfixing. Fix forward; gate with a feature flag if other features shouldn't ship yet.
• Mention the ticket number in every commit.
• Understand git internals before relying on graphical tools (GitKraken, etc.).

<work-type>/<TICKET-NUMBER>
# examples
feature/SPPLT-1234        # new feature
enhancement/ASE-5678      # improving existing functionality
bugfix/ASE-123            # prod bug
defect/ASE-3456           # caught in QA, pre-release
techdebt/SPPLT-4567       # refactor / cleanup
maintenance/ASE-6789      # dep updates, routine ops

• Always include the JIRA ticket number after the prefix.
• Keep names short and clear — no extra description in the branch.
• Make sure the prefix matches the actual work. A bug fix is not a feature.

• Name can be anything human-readable (e.g. "Show Portfolio Link").
• Key must be a valid JS property name in camelCase — e.g. showPortfolioLink NOT show-portfolio-link. This lets it be used with dot notation in Vue components and templated as {{ showPortfolioLink }}.
• Skill assessment flags: name Skill Assessment: {Skill}, key skill-assessment-{hyphenated-skill-tag}, type Kill Switch, tag skill-assessment. The key cannot be changed after creation — verify before saving.

// Inside a component
computed: {
  ...mapFeatureFlags('myFeature', 'myOtherFeature'),
  // with fallbacks
  ...mapFeatureFlags({ canUploadPhotos: false, minimumPhotos: 5 })
}

// In a Nuxt middleware / store
if (await this.$getFeatureFlagAsync('achievementsEnabled')) { /* … */ }

• All schema changes live in version control next to the application code they belong to.
• Use a tool that records which changes ran in which environments and the result (Laravel migrations).
• Migrations are for schema only. No data seeding, no command execution inside a migration.
• Required data seeding → a Seeder class registered in DatabaseSeeder.
• One-time production data changes → a One-Time Operation class run as part of the release.
• Always design for rollback so a failed change can be reverted.

For one-off production tasks (data backfills, cache priming) the laravel-one-time-operations package automatically runs each operation exactly once and tracks completion.

# 1. Generate
php artisan make:one-time-operation UpdateUserRoles

# 2. Implement (app/OneTimeOperations/…)
class UpdateUserRoles extends OneTimeOperation {
  public function handle() {
    User::whereNull('role')->update(['role' => 'user']);
  }
}

# 3. Run (this fires automatically as part of deploy)
php artisan one-time-operations:run

• Commit the operation file — it's the audit trail.
• Test locally and in staging before letting prod run it.
• Name them descriptively — the class name is the deploy log.
• Delete the file once it has run successfully in every environment so the codebase stays clean.

• Trunk-based development — work integrates to main at minimum daily.
• Every change has automated tests before merge.
• Work is tested with all other work automatically on merge.
• When the build is red, all feature work stops until it's green.
• New work does not break delivered work.

• Your work must have test coverage.
• Shared understanding that we will never push untested changes.
• Use BDD to define tests, TDD to implement them.
• When something breaks the pipeline, harden the gate so it can't break the same way again.

• The Beyoncé Rule: "If you liked it, then you shoulda put a test on it." — SWE@Google.
• Run faster tests first. Unit before component, system, functional. — Continuous Integration.
• Write a test for every defect so it can never resurface.
• One assert per test. Faster diagnosis when something fails.
• When an integration test fails, add the unit test that would have caught it cheaper. — The DevOps Handbook.
• Visualize coverage. Fail the validation suite if it drops below threshold.
• Developers own testing. Testers exist for exploratory, usability, and acceptance work — not as the safety net.

When production code changes, tests should react like this:

Only the last row touches existing tests. If you find yourself rewriting tests during a refactor, the tests were too tied to implementation.

• Tech debt is owned by each pod and stream-aligned.
• Creating a tech-debt ticket is fast, easy, and accessible.
• Tech debt is visible to PMs and discussed in refinement.
• Tech debt is not a backlog trash bin — it's curated with intent.
• It becomes a Tech Initiative when it spans pods, requires architectural change, or exceeds 1–2 days per engineer.

• Clear title — what and where.
• Description & context — why the debt exists.
• Impact — technical / product risk, performance, delivery speed.
• Acceptance criteria for resolution.
• Optional subtasks for complex work.
• Pod label + optional fe-tech-debt / be-tech-debt.

• You hit a workaround or shortcut introduced under deadline pressure.
• You see unaddressed issues from prior code, migrations, or deprecated patterns.
• Code violates team standards, lacks tests, or is hard to maintain.
• You spot duplicated logic / copy-paste blocks that should be centralized.
• A tech decision is slowing delivery or complicating testing.
• You postponed a refactor or test-coverage task to unblock a feature.

• AI is a First-Draft Generator, Not an Author. Treat output as a starting point requiring human refinement.
• Context is the Multiplier. Output quality is a direct function of input context — references to existing patterns, explicit constraints, scope boundaries, relevant docs.
• Human Review Owns Architecture and Learning. AI helps with syntax and boilerplate. Humans own architectural fit, pattern consistency, and knowledge transfer.

• Necessity. Is every line necessary? Could this be simpler?
• Patterns. Does it match our established patterns?
• Readability. Would a teammate understand it without explanation?
• Efficiency. Is this reasonably efficient, or just "working"?
• Test scope. Are tests focused, or bloated and redundant?

• No test file over 300 lines.
• No redundant test cases. No vague descriptions like "should work correctly".
• Specify exact scenarios upfront — don't let AI decide coverage.
• Delete excess when AI over-generates (it will).

• AI-assisted commit messages are fine if accurate; generic messages are unacceptable regardless of source.
• PR description: what can be AI-assisted; why and non-obvious decisions must be human-written.
• If a PR is >50% AI-generated, note it in the description.
• Keep PRs focused. AI makes large changes easy to generate — that doesn't make them good.