Team Info

Team Delivery Framework

This document consolidates the core practices, conventions, and working agreements that guide our team’s delivery process. As the project has evolved, we’ve moved from informal idea‑gathering in GitHub issues to a more structured and predictable workflow. This wiki serves as the single source of truth for how we plan, estimate, categorize, and execute work.

Here you’ll find our shared guidelines on:

• Story point estimation and sizing
• Issue workflow and lifecycle
• Issue types and categorization
• Sprint structure and cadence
• Scrum ceremonies and expectations
• Team norms that support transparency, predictability, and continuous improvement

The goal is not to create rigid rules, but to ensure that everyone—new and existing team members alike—has a clear, consistent understanding of how we work together.

Scrum Overview

Our team follows a lightweight, practical interpretation of Scrum. We use Scrum not as a strict rulebook, but as a framework that helps us:

• Deliver value incrementally
• Maintain a predictable cadence
• Collaborate closely with stakeholders
• Continuously inspect and adapt our process

Key Scrum principles we embrace:

• Empiricism — decisions are based on observation, transparency, and learning
• Iterative delivery — work is broken into manageable increments
• Cross‑functional collaboration — the team collectively owns outcomes
• Continuous improvement — every sprint is an opportunity to refine how we work

While we adapt Scrum to fit our context, the underlying values—focus, commitment, openness, respect, and courage—remain central to how we operate.

Sprint Structure

We work in three‑week sprints, a cadence chosen to balance meaningful delivery with enough time for discovery, refinement, and stakeholder engagement. Each sprint includes the following ceremonies:

Sprint Planning

• Held at the start of each sprint
• The team reviews the prioritized backlog, clarifies requirements, and commits to a realistic set of deliverables
• Story point estimates and acceptance criteria must be finalized before work begins

Daily Standups

• Short, focused daily check‑ins
• Each team member shares progress, plans, and blockers
• The goal is alignment, not status reporting

Sprint Review (with external users/stakeholders)

• Demonstration of completed work
• Opportunity for feedback from product owners, domain experts, and end users
• Helps validate direction and uncover new insights early

Sprint Retrospective

• Internal team reflection on what went well, what didn’t, and what we want to improve
• Action items are documented and carried into the next sprint
• This ceremony is essential for maintaining a healthy, adaptive workflow

Story Point Estimation Guidelines

Story point estimation is a core practice in our delivery workflow. Early in the project, we used GitHub issues as a place to capture ideas and rough planning notes. As the project has matured, we now maintain a more structured backlog, and this document formalizes our approach to story point estimation.

This topic consolidates the original guidance from Issue #1 in the repository github.com and expands it into a stable reference for ongoing team use.

Purpose of Story Point Estimates

Story points help the team:

• Develop a shared understanding of the work.
• Identify unknowns, risks, and assumptions early.
• Plan sprints with realistic expectations.
• Track velocity trends over time.
• Facilitate conversations that lead to clarity, not precision.

The value is not in the number itself, but in the discussion that produces it. As the original issue noted, estimates are “imperfect but well understood” when the team aligns on what each point value represents. github.com

Estimation Scale

Story Points	Approximate Effort	Typical Meaning
1	1 hour to half a day	Very small, low‑risk, well understood
2	Full day	Straightforward work with minimal uncertainty
3	1–3 days	Moderate complexity or some unknowns
5	~1 week	Larger effort, multiple moving parts
8	Full sprint	Very large; likely needs refinement or splitting

Handling Items Larger Than 8 Points

Any backlog item that appears to exceed 8 story points should be split into smaller, well‑defined tasks before entering a sprint. Work of this size typically indicates:

• Significant unknowns or unclear requirements
• Multiple logical deliverables bundled together
• Cross‑team dependencies
• High technical risk or architectural impact

Breaking these items down ensures that:

• Each piece fits within a sprint
• The team can estimate more accurately
• Work flows through the system more predictably
• Progress is visible and measurable
• Risk is reduced through incremental delivery

This practice aligns with widely accepted agile guidance that large stories (often called epics) should be decomposed until they are small enough to estimate reliably and complete within a single iteration.

References:

• Atlassian Agile Coach – Splitting User Stories
• Scrum Alliance – Why Smaller Stories Improve Flow
• Mike Cohn – Breaking Down Epics for Better Estimation

Definition of Done / Acceptance Criteria

Every estimated backlog item must include:

• A clear estimate, and
• Either a Definition of Done or explicit Acceptance Criteria

This ensures that the team is estimating against a shared understanding of what “done” means, reducing ambiguity and rework.

Why Fibonacci?

The Fibonacci sequence (1, 2, 3, 5, 8, …) is widely used in agile estimation because:

• It reflects the increasing uncertainty of larger tasks.
• It discourages false precision.
• It helps teams think in terms of relative complexity rather than absolute time.

References:

• Scrum.org – Understanding Story Points and Estimation
• Mountain Goat Software (Mike Cohn) – Agile Estimating and Planning
• Atlassian Agile Coach – Story Points and Estimation

(These are general references to well‑established agile practices; they complement the project‑specific guidance from the original issue.)

Best Practices

• Estimate collaboratively — the conversation is the real value.
• Prefer smaller stories — if something feels like an 8, consider splitting it.
• Avoid equating points to hours — points measure complexity, not time.
• Re‑estimate only when necessary — major scope changes, not minor adjustments.
• Use velocity as a trend, not a target — it’s a planning tool, not a performance metric.

Historical Context

This guidance originated from early project planning discussions and was first captured in Issue #1 of the repository. As the team’s workflow evolved, this content has been formalized here to support consistent estimation practices going forward. github.com

Developer Contract

To maintain a high standard of quality, consistency, and maintainability across the project, all team members follow a shared set of engineering practices. These expectations form our developer contract — a lightweight agreement that ensures our codebase remains healthy, predictable, and easy to evolve.

This contract is not about gatekeeping; it’s about supporting each other, reducing friction, and ensuring that our work is sustainable over the long term.

Code Quality and Linting

All code must pass the project’s linting rules before being merged. Linting helps us:

• Catch common errors early
• Maintain consistent style across contributors
• Reduce cognitive load when reading unfamiliar code
• Avoid formatting‑related noise in pull requests

Linting is enforced through automated tooling (e.g., ESLint, Prettier, or language‑specific equivalents). Developers are expected to run linting locally before opening a pull request.

References:

• ESLint – Pluggable JavaScript Linter
• Prettier – Opinionated Code Formatter
• JetBrains / VS Code documentation on linting integrations
• Backend structure
• Frontend structure

Test Coverage (Minimum 80%)

We require at least 80% test coverage for all new or modified code. This threshold is not arbitrary — it ensures:

• Core logic is validated
• Regressions are caught early
• Refactoring is safer
• The team has confidence in the system’s behavior

Coverage alone is not the goal; meaningful tests are. Developers should prioritize:

• Unit tests for core logic
• Integration tests for workflows
• Edge cases and failure scenarios

Coverage reports are generated automatically in CI and must meet the threshold before merging.

References:

• Martin Fowler – Test Coverage
• Kent Beck – Test-Driven Development: By Example

Meaningful Commit Messages (Conventional Commits)

We use the Conventional Commits specification to ensure that commit messages are structured, readable, and machine‑parsable. This helps with:

• Automated changelog generation
• Clear project history
• Easier code reviews
• Predictable versioning (when applicable)

Commit Message Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Common Types

Type	Meaning
feat	A new feature
fix	A bug fix
docs	Documentation changes
style	Formatting, whitespace, lint fixes (no logic changes)
refactor	Code changes that neither fix a bug nor add a feature
test	Adding or updating tests
chore	Maintenance tasks, build scripts, tooling

Examples

feat(api): add endpoint for waste stream summary

fix(ui): correct alignment issue in table header

docs: update story point estimation guidelines

refactor: simplify validation logic for permit creation

Reference:
Conventional Commits — https://www.conventionalcommits.org

Documentation Updates

Documentation is part of the product. Any change to a component, workflow, or behavior that has corresponding documentation must include an update to the relevant wiki page.

This ensures:

• New team members can onboard quickly
• Stakeholders have accurate information
• Technical debt does not accumulate silently
• The wiki remains a living, trustworthy resource

Documentation updates should be included in the same pull request as the code change whenever possible.

Pull Request Expectations

Every pull request should:

• Be small and focused
• Include meaningful commit messages
• Pass all linting and tests
• Include documentation updates when applicable
• Provide context in the PR description (what changed and why)
• Request review from at least one team member

Small, well‑scoped PRs reduce review time, lower risk, and make it easier to revert or adjust changes if needed.

Rationale Behind the Developer Contract

These practices are grounded in widely accepted engineering principles:

• Consistency reduces cognitive load — teams move faster when code looks familiar
• Automation prevents regressions — linting, testing, and CI catch issues early
• Documentation preserves knowledge — especially in long‑running government projects
• Clear commit history accelerates debugging — structured messages matter
• Quality compounds — good habits early prevent major refactors later

References:

• Google Engineering Practices – Code Review Guidelines
• ThoughtWorks Technology Radar – Engineering Best Practices
• Atlassian – Code Review Best Practices