Linting, Type Hints,
and First Real PRs.

FEAST Academy | Week 2 | Summer 2026 | v0.5.0
Where we left off

Week 1: what you built.

Setup

Environment running

Backend on 8000, frontend on 5173, map in browser.

Trace

Endpoint traced

One request through frontend, backend, and database.

Vision

Vision plan written

3+ investigation areas, current state, target state, sequenced.

Issues

Issues filed

Bugs and improvements with area labels. Our backlog.

Config

Context file created

Your project context file. We review these today.

Week 2 · Recap ● Week 1 summary
Vision plan themes

What you found.

Themes

Common findings

[Instructor: fill from LLM digest. What did multiple students identify?]

Gaps

Areas with no coverage

[Instructor: which investigation areas did nobody explore?]

Debate

Sequencing disagreements

[Instructor: where did students disagree on priority order?]

Surprise

One-person findings

[Instructor: something only one student caught that everyone should hear.]

Week 2 · Digest ● Pre-populated from LLM digest of vision plans
Part one

The review
pipeline.

15 minutes · every PR from now on
Quality gates

Every PR (pull request) goes through three layers.

Layer 1 · This week

Automated CI (continuous integration)

GitHub Actions runs flake8 on every pull request. Red X means it cannot merge. The linting student (#24) sets this up first.

Layer 2 · This week

Human peer review

One student reviews every PR. Check: does the code match the stated intent? Post at least one substantive comment.

Layer 3 · Week 3

LLM adversarial review

A student runs a structured adversarial review in a fresh LLM session and posts findings as PR comments.

Week 2 · Review pipeline ● Three layers
Layer 1

CI: green check or red X.

How it works

  • Push a commit or open a PR
  • GitHub Actions runs the flake8 workflow automatically
  • Green check = passed, Red X = failed
  • Click into details to see which lines have issues
  • Fix, push again, check reruns

Rules

  • You cannot merge with a red X
  • CI failures are your responsibility to fix
  • Run flake8 locally before pushing to avoid surprises
  • If CI is broken for everyone, that is the top priority
Week 2 · Review pipeline ● CI checks
Layer 2

Reviewing code: what to look for.

  • 1
    Read the diff, not just the description.
    Does the code actually do what the PR says it does? Check line by line.
  • 2
    Look for edge cases.
    What inputs would break this? What happens if the data is missing or unexpected?
  • 3
    Check naming and clarity.
    Could you maintain this code six months from now without the PR description?
  • 4
    Leave at least one real comment.
    Show that you read it. If something is confusing, say so. If something is good, say that too.
Beyond this project: You're learning to give and receive critical feedback clearly and constructively. This skill appears in every professional role. Code review is practice for the hardest version of it.
Week 2 · Review pipeline ● Peer review
Every PR

The PR template: fill in every section.

Section 1

Summary

One or two sentences. What does this PR do and why.

Section 2

Changes

Bullet list of what you actually changed.

Section 3

Test plan

How you verified it works.

Section 4

Tradeoffs

Alternatives you considered and why you chose this.

Section 5

Checklist

CI passes, reviewer assigned, issue linked.

"See diff" is not a useful PR description. The template exists for a reason.

Week 2 · Review pipeline ● PR template
Part two

Git workflow
for teams.

15 minutes · branches, PRs, commit conventions
Three levels

Branches: main, dev, and yours.

main

Stable / deployed

The production version. You never push directly to main. Only merged from dev at the end of week 6.

dev

Integration

Where feature branches merge. Always branch from an up-to-date dev. Pull before you branch.

feature/issue-N-desc

Your work

One branch per issue. Name it after the issue: feature/issue-24-linting

git checkout dev && git pull && git checkout -b feature/issue-NUMBER-short-desc
Week 2 · Git workflow ● Branch strategy
The full cycle

From issue to merged code.

1
GitHub
File an issue describing the work
2
Terminal
Create a feature branch from dev
3
Editor
Write code, make commits
4
Terminal
Push to GitHub
5
GitHub
Open PR, link issue, request reviewer
6
GitHub
Respond to feedback, push fixes
7
GitHub
CI green + approved = merge to dev

Keep PRs under ~200 lines of changed code (non-test). Smaller PRs get reviewed faster and have fewer bugs.

Week 2 · Git workflow ● PR lifecycle
Messages that help

Write commit messages for future you.

Good

Add flake8 configuration and pre-commit hook (#24)
Fix duplicate store count in household step (#47)
Add type hints to simulation endpoint (#18)

Bad

fixed stuff
updates
WIP
asdfasdf

Imperative mood ("Add", not "Added"). Reference issue numbers. One logical change per commit.

Beyond this project: A commit message is a micro-conversation with people you may never meet, who will read it without context. Writing clearly for an absent audience transfers to emails, documentation, and any situation where your reasoning needs to outlast the conversation.
Week 2 · Git workflow ● Commit conventions
Muscle memory

The daily git rhythm.

Starting work
git checkout dev
git pull
git checkout -b feature/issue-N-desc
While working
git status
git add <specific files>
git commit -m "message (#N)"
Sharing work
git push -u origin <branch>
Open PR on GitHub
Request a reviewer

When in doubt at any point: git status

Week 2 · Git workflow ● Daily rhythm
Part three

Edge case
brainstorming.

10 minutes · LLMs as thinking partners
The pattern

Interview first, then test.

Don't do this

"Write tests for has_resources()"

Skips the thinking. The tool writes generic tests that miss the real risks.

Do this

"has_resources() checks income against a threshold that varies by household size. What edge cases should I test?"

You think about the problem. The tool helps you think more completely. You write the tests.

Week 2 · Edge cases ● Interview first
Example

has_resources(): what could go wrong?

Ask the tool: "What edge cases should I consider for a function that checks household income against a size-dependent threshold?"

Boundary

Income exactly at threshold

$10,000 for single, $15,000 for 2-person, $25,000 for 3+. What happens at the boundary?

Data

Household size of zero

Is this possible in the data model? If not, should the function guard against it?

Range

Negative income

Census data can have negative values for certain income categories. How does the function handle it?

Your job: evaluate which edge cases are real risks given the data model, and write tests for those.

Week 2 · Edge cases ● Concrete example
Part four

Writing code
with AI tools.

10 minutes · first draft, not final answer
The iterative pattern

Shape the output. Don't just accept it.

  • 1
    Start with intent, not instructions.
    Describe what you need and why. Let the tool propose an approach.
  • 2
    Read the output critically.
    Does the naming make sense? Are there magic numbers? Is the structure obvious?
  • 3
    Ask for best practices.
    The tool knows conventions you might not. Use that knowledge, but verify it.
  • 4
    Ask about complexity.
    Is this the simplest way? What could you remove without losing functionality?
  • 5
    Verify readability.
    Would someone reading this six months from now understand it without context?
Week 2 · Iterative coding ● Five steps
The distinction in practice

Vibe coding vs. agentic engineering.

Vibe coding

Prompt, accept, move on.

Code that works but that nobody can maintain. You skipped the engineering: no spec, no review, no decision record. When it breaks, you start over.

Agentic engineering

You do the engineering. The agent does the typing.

Spec the work, shape the output, review critically, document the decision. The agent handles syntax; you handle judgment.

Remember the focus shift from Week 1: review pipelines, git workflow, architecture decision records, iterative coding. Everything you learned today is in the engineering column.

Week 2 · Iterative coding ● The distinction
Coming in week 3

Preview: structured planning.

Many CLI agents have built-in planning features that create a structured plan before making changes. Same principle as the iterative pattern: start with intent, get a plan, review it critically, then execute.

We'll use structured planning hands-on in Week 3. For now, just know it exists and that it follows the same "review before accepting" principle.

Week 2 · Iterative coding ● Planning preview
Part five

Architecture
Decision Records.

5 minutes · document the why
The format

Four fields. Keep it short.

Field 1

Title + Status

Short description of the decision. Status: proposed, accepted, or superseded.

Field 2

Context

What prompted the decision. The problem or constraint you were responding to.

Field 3

Decision

What you chose and why. Be specific.

Field 4

Alternatives

What else you considered and why you rejected it.

ADR template is at templates/adr-template.md. The linting student writes the first one this week.

Week 2 · ADRs ● Template
Example

ADR: Ignore E501 in flake8.

Decision: Ignore E501 (line length)
Context: The project convention allows long lines. The existing codebase has many lines over 79 characters.
Decision: Ignore E501 in the flake8 configuration.
Alternative: Enforce a 120-character limit. Rejected because reformatting all existing long lines would create noisy diffs during onboarding.

That's an ADR. Short, specific, and it answers the question future you will have.

Week 2 · ADRs ● Example
Part six

Context file
check-in.

5 minutes · quick round
Group review

Show your project context file. One minute each.

What to check

  • Are you capturing useful information?
  • Is anything missing that would help the tool help you?
  • Are your project conventions documented?
  • Did you add any patterns you learned this week?

Good signs

  • Specific file paths and function names
  • Build and test commands that actually work
  • Architecture notes in your own words
  • Gotchas you discovered during setup
Week 2 · Context files ● Review
Part seven

This week's
work.

Issues from the backlog · paired J with S
Backlog issues

Five issues, five students.

Priority

#24: Incorporate linting

Add flake8 to dev deps, create config (ignore E501, max-complexity 10), add GitHub Actions CI workflow. Ship CI first so everyone benefits. Write an ADR for your choices.

Parallel

#18, #19, #20: Add type hints

Three students, one module each. Start from function signatures and work inward. First PR should be small and focused.

S student

First tests: household.py

Set up pytest. Write tests for has_resources(), get_monthly_trip_count(), get_color(). Test boundary values. Use edge case brainstorming pattern from earlier.

Week 2 · Assigned work ● Issues
Async this week

Solo work.

  • 1
    Update your project context file
    Add patterns you learned this week. Build and test commands. Architecture notes.
  • 2
    File at least two more issues
    Things you discover while working on your assigned issue. Keep building the backlog.
  • 3
    Review one teammate's PR
    Use the review checklist. Post at least one substantive comment.
  • 4
    Start on your assigned issue
    Create a feature branch. Make small commits. Open a PR by Friday.
Week 2 · Solo work ● Deliverables
Week 2 recap

Four engineering skills you practiced today.

Code review

CI + peer review on every PR. Evaluating correctness, not just syntax.

Coordination

Branches, commits, PRs. The workflow that keeps a team in sync.

Iterative shaping

The agent drafts, you refine. First output is never the final answer.

Decision records

ADRs: documenting not just what you chose, but why.

All four are in the “engineering column” from Week 1. The agent handles syntax. You handle these.

Next week: LLM adversarial review and structured planning for feature work.

FEAST Academy · Week 2 ● End