Engineering — How We Work

• Mission — the stream's purpose.
• Systems Owned — services and capabilities the stream is responsible for.
• Data Ownership — what data domains the stream owns and who consumes them.
• Boundary Clarifications / Areas of Contention — where ownership overlaps and how the line is drawn.
• Dependencies — what other streams this one depends on.

• Cross-team work — knowing whose code you're touching.
• Ownership disputes — boundary clarifications resolve "whose feature is this?"
• Dependency questions — what your stream consumes vs. owns.
• Onboarding to a new domain — use the /value-stream Claude skill to load all pages at once.

Undifferentiated heavy lifting (AWS) — work necessary for the product to function but creating zero competitive advantage. SSR, CI/CD, auth flows, build pipelines — table-stakes infrastructure that doesn't separate us from competitors. Differentiation is the learning experience we build on top: library search, recommendations, lesson player, retention features.

Always ask: "Does building this ourselves give us a meaningful advantage over adopting a proven solution?" If no, every hour spent building is an hour traded away from work that moves the needle.

Custom infrastructure costs the years of maintenance, not the weeks of building: upstream upgrades, production debugging, onboarding drag. When we adopt a framework, thousands of OSS engineers find and fix edge cases before we do — leverage we can't replicate at our size.

1. Default to Adopt for undifferentiated infrastructure. The burden of proof is on building, not adopting.
2. Build only where it creates meaningful differentiation — the learning experience or a domain problem nothing existing solves well.
3. Evaluate with a total-cost-of-ownership lens. Ongoing maintenance + onboarding + opportunity cost — not just the build estimate.
4. Document what we're choosing not to build. Keep the opportunity cost visible. Make every decision intentional.

• 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.

Released via npm run release:patch | release:minor | release:major from the package repo (see auth README → Publishing).

• 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 the preview environment before letting prod run it.
• Name them descriptively — the class name is the deploy log.
• Keep the file after it has run — the package tracks completion, and the file stays as the permanent audit record.

• 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.