Final assignment

What you will be able to do

Use the whole course on one new piece of work, on your own. You add one feature and repair one defect, with an assistant or with the supplied transcripts. You keep the evidence that a reviewer needs. That is a clear task brief, a reviewed and focused diff, checks of the behaviour, and the reasons for each suggestion that you accepted or rejected.

Before you startWhat to know and to have readyAbout 180 minutes

What you need to know

• You completed Modules 1 to 5. Each part below names the lessons that it uses.
• You do not need the case studies for this assignment. The certificate asks for at least one of them.

What you need on your computer

• The labs clone ~/projects/nextia-learning-labs, with C15/snapshots/ and C15/transcripts/. To get the newest version, run git -C nextia-learning-labs pull in ~/projects.
• Python 3.14 and Git, as in the course.
• A coding assistant is optional. Route 1 below uses your own assistant. Route 2 uses the recorded sessions, and needs no assistant, no account and no money.

Tested on macOS (Apple silicon) with Python 3.14.6. The Windows commands are written, not tested.

The situation

Grace sends Amira two emails on Monday morning. Both are constructed for the course.

The request. “For the Monday meeting, I need to see how urgent the open tickets are. Can the report also count the tickets of each priority, 1, 2 and 3? I still need the normal report as it is: my spreadsheet reads it.”

The bug report. “Sam saved this week’s export from the web form as WEEK.CSV, and the program stops: cannot read WEEK.CSV: use a .csv or .json file. It is a normal CSV file. With the name week.csv, it works.”

You are Amira. You deliver both on one branch, with one pull request.

Choose your route

Both routes are marked with the same table, under Check your evidence.

	Route 1: your own assistant	Route 2: the supplied transcripts
Project	a copy of end-of-m05, the course-end project	a copy of start, the course’s first snapshot
Feature	Grace’s priority counts, above	the --category option, from C15/emails/grace-feature-request.md
Defect	the WEEK.CSV bug, above	Grace’s category names bug, from C15/emails/grace-bug-report.md
Suggestions	your own sessions, with your own prompts	the recorded sessions and their .patch files in C15/transcripts/

In Route 2, you already know one good answer from the course. So the evidence is in your decisions. Write your own briefs, choose among the recorded suggestions, and explain each choice. Do not copy files from the later snapshots: a reviewer would see it in your diff.

The parts below describe Route 1. Each part names what is different in Route 2.

Set up

1. Copy the snapshot, then make the environment and the repository:

   macOS and Linux

   cd ~/projects
   cp -R nextia-learning-labs/C15/snapshots/end-of-m05 ticket-cleaner-final
   cd ticket-cleaner-final
   python3 -m venv .venv
   source .venv/bin/activate
   python -m pip install -r requirements-lock.txt
   git init
   git add -A
   git commit -m "Start"
   git switch -c final/priority-and-csv-name
   python -m pytest

   Windows

   cd ~\projects
   Copy-Item -Recurse nextia-learning-labs\C15\snapshots\end-of-m05 ticket-cleaner-final
   cd ticket-cleaner-final
   python -m venv .venv
   .venv\Scripts\Activate.ps1
   python -m pip install -r requirements-lock.txt
   git init
   git add -A
   git commit -m "Start"
   git switch -c final/priority-and-csv-name
   python -m pytest

   The last line is 42 passed. In Route 2, copy start instead, and the last line is 24 passed.

2. Make the evidence file next to the project, outside the repository, so that you do not commit it by accident: ~/projects/final-evidence.md. After each part, copy into it what the part asks for.

Rules for every part

• Work on the branch. Commit before each assistant session, so that git restore . can undo it, as in Context and boundaries.
• Give the assistant ASSISTANT-SCOPE.md with each task. It changes only the files that the task needs, and you run git commit yourself. In Route 2, start has no scope file yet: write one first.
• No new dependency. If an assistant proposes one, check it as in Verify dependencies, and record your decision.
• Never paste .env, a token or real customer data into a prompt.
• Keep every prompt that you send and the assistant’s reply, or the name of the transcript that you used.

Part 1: two task briefs

Uses Problem and acceptance criteria and Supply relevant context.

1. Write docs/tasks/by-priority.md from Grace’s request. Give the problem, the scope (what is not part of the task), and numbered acceptance criteria. Each criterion names the command or test that will show it. Grace’s last sentence is a criterion too.

2. Reproduce the bug before you write about it. Copy the export with a new name, and run it:

   cp data/web-form-export.csv data/WEEK.CSV
   python -m ticket_cleaner data/WEEK.CSV

   Output

   ERROR ticket_cleaner: cannot read the tickets from data/WEEK.CSV: cannot read WEEK.CSV: use a .csv or .json file

   The exit code is 1. Decide: is it the environment or the code? Use the checks of Reproduce first. Then delete data/WEEK.CSV (Windows: Remove-Item data\WEEK.CSV).

3. Write docs/tasks/csv-name-bug.md: the steps to reproduce, observed, expected, the environment, and the evidence of done. Commit both briefs.

Route 2: write the brief and the bug report from Grace’s two emails in C15/emails/, without looking at the course’s versions.

Evidence for part 1: the two briefs, and one sentence on how you decided “environment or code”.

Part 2: repair the defect

Uses Ask for evidence and Choose meaningful checks.

1. Ask your assistant for a hypothesis with the line of code, and for a test that would show it. Do not ask for a fix yet.
2. Add a regression test that fails on the current code, for the reason that the hypothesis predicts. Run it, and keep the output.
3. Ask for the smallest fix. Review the diff before you run it. Then run all the tests, ruff, and Grace’s case.
4. Prove the test: put the unfixed file back from main with git restore --source=main, run the tests, and restore the fixed file.
5. Commit the test and the fix together.

Route 2: compare the recorded sessions bug-fix-blind, bug-fix-blind-small, bug-fix-blind-no-map and bug-fix-evidence, and the test sessions tests-mirror and tests-failing-first. Choose what you keep, and apply it with git apply or by hand.

Evidence for part 2: the prompts (or the transcripts that you used), the failing test output, the output with the unfixed file from main, and git show --stat of your commit.

Part 3: add the feature

Uses Break work into steps, Inspect the diff and Refactor selectively.

1. Give the assistant your brief and the files that it needs. Ask for a plan first, if the task touches more than two files.
2. Review the diff line by line with docs/review-checklist.md. Mark each change as needed, unrelated or risky. Undo what the task does not need, even if it looks like an improvement.
3. Write or correct the tests, so that each acceptance criterion has one. The expected values come from Grace’s request and the data, never from a run of the new code.
4. Run every check, and commit.

Route 2: compare feature-vague, feature-bounded, feature-bounded-small, feature-plan-first and refactor-grows with your brief. Use the review checklist of Inspect the diff. Some recorded diffs fail ruff format --check, and refactor-grows has a test that depends on the width of the terminal. Decide what you do about each.

Evidence for part 3: your review of the diff (the marks, and what you undid), the test for each criterion, and the outputs of python -m pytest, ruff check . and ruff format --check ..

Part 4: explain, document and hand over

Uses Document decisions and Independent comprehension.

1. Update the README, and add a decision to DECISIONS.md for each choice that a reasonable person could make differently. Give each claim its evidence.
2. Write docs/pull-request.md with the requirement → change → evidence table. Add Use of a coding assistant: what it suggested, what you accepted, changed or rejected, and why.
3. Break one consequential line on purpose. Note the test that fails, then restore the line.
4. Push both branches to a new bare remote, clone it into a new folder, make a fresh environment, and run every check of the description there.

Evidence for part 4: docs/pull-request.md, the new decisions, the line that you broke with the test that caught it, and the outputs from the fresh clone.

Common mistake

The baseline test fails after the feature

Symptom: after the assistant’s change, python -m pytest prints FAILED tests/test_baseline.py::test_report_of_the_sample_file_is_unchanged. The assistant proposes to update the expected report in the test.

Cause: the change adds the priority counts to every report. Grace asked to keep the normal report as it is, because her spreadsheet reads it. The baseline test from Repository preparation pins exactly that.

Fix: do not edit the baseline test to make it pass. Change the code, so that the counts appear only when someone asks for them, and test that too. If the team decides to change the normal report, that is a decision with Grace. Record it in DECISIONS.md, and only then change the baseline.

Common mistake

The README test fails after a new option

Symptom: FAILED tests/test_readme.py::test_every_option_of_the_command_is_in_the_readme, with 1 failed, 44 passed in the course team’s run.

Cause: the new option is in --help, but not in the README’s options table. The test from Document decisions caught the drift.

Fix: add the row to the table, in the same commit as the option. Do not delete the test.

Check your evidence

For each required item, choose the result that matches your evidence. The course is complete when all four items are demonstrated. If an item is not, fix that part and check it again, as many times as you need.

Required item	Demonstrated	Partially demonstrated	Not yet demonstrated
Clear task brief	Both briefs give the problem and the scope. Each acceptance criterion names the command or test that shows it, and “keep the normal report” is one of them. The bug report has a minimal input, the observed and the expected output, and the environment check.	The briefs are clear, but one criterion has no check, or the bug report has no minimal input.	A brief only repeats the email, or the work started before any brief existed.
Reviewed focused diff	git diff --stat main lists only the files that the two tasks need. You can show your marks on the assistant’s diff, and what you undid. Each commit has one purpose.	The diff is focused, but the review is not written down, or one commit mixes the fix and the feature.	The diff has unrelated edits, a new dependency without a decision, or a change that you cannot explain.
Behaviour-based validation	The regression test failed before the fix and passes after it, shown with the unfixed file from main. Each criterion has a test whose expected value comes from the requirement. The baseline and README tests pass unchanged, and the checks pass in a fresh clone.	The tests pass, but one was not shown failing first, or one expected value was copied from a run.	Tests were changed to agree with the code, the baseline test was edited without a decision, or there is no fresh-clone run.
Explanation of accepted and rejected suggestions	The pull request names each suggestion that you accepted, changed or rejected, with the reason and the evidence. You can explain every consequential line, and you name what still needs Grace’s review.	The explanation covers the accepted changes but not the rejected ones, or a reason has no evidence.	The pull request says “the assistant did it”, or it makes claims that no run checked.

Some work is not yet demonstrated, even if the rest is correct: a secret or customer data sent to an assistant, or an unknown change run outside a throwaway copy.

Note

The course site does not collect submissions yet. Check your own work with this table, or ask a colleague to check it with the same table. Keep final-evidence.md.

Show model evidence for Route 1

This is the course team’s model solution, written without an assistant. Yours can differ and still be demonstrated.

The defect. The cause is in read_rows() in ticket_cleaner/files.py. It compares path.suffix with ".csv" exactly, so .CSV falls through to the error. It is the code, not the environment: the same command fails in a fresh copy, and the message is about the file name, not a module. The regression test:

tests/test_files.py (new test)

def test_csv_name_in_capital_letters(tmp_path):
    # Grace's colleague saved the export as WEEK.CSV.
    path = tmp_path / "WEEK.CSV"
    path.write_text("id,status\nT-1001,open\n", encoding="utf-8")
    assert read_rows(path) == [{"id": "T-1001", "status": "open"}]

The fix compares path.suffix.lower(), for .csv and for .json. After the fix, the tests give 43 passed, and WEEK.CSV gives 12 rows: 12 valid, 0 rejected. At the end of the task, with files.py put back from main, the tests give 1 failed, 44 passed: FAILED tests/test_files.py::test_csv_name_in_capital_letters.

The feature. A flag --by-priority adds a key by_priority with the counts of the selected tickets for "1", "2" and "3", also when a count is 0. Without the flag, the report is unchanged, so the baseline test passes as it is. The real outputs:

by_priority, with --by-priority

data/tickets.csv:                            {"1": 1, "2": 2, "3": 1}
data/web-form-export.csv:                    {"1": 3, "2": 5, "3": 2}
data/web-form-export.csv --category login:   {"1": 2, "2": 2, "3": 0}

The sample file has 4 open tickets, and the export has 10. The model adds two CLI tests (the key only with the flag; the counts with --category login) and one README row.

The whole change: 45 passed, All checks passed!, 24 files already formatted.

git diff --stat main

 README.md                |  1 +
 tests/test_cli.py        | 18 ++++++++++++++++++
 tests/test_files.py      |  7 +++++++
 ticket_cleaner/cli.py    |  9 ++++++++-
 ticket_cleaner/files.py  |  5 +++--
 ticket_cleaner/report.py |  8 ++++++++
 6 files changed, 45 insertions(+), 3 deletions(-)

For a domain review: does Grace’s spreadsheet still work if someone uses the flag by mistake? Only Grace knows. And are priorities always 1 to 3? The rules reject other values today. A new priority would need a change to the rules, and a decision.

Optional stretch work

These tasks are not required for completion.

• Do the other route as well, and compare the two pull requests.
• Ask two different assistants, or the same one twice, for the feature. Compare the diffs with the same review checklist, and record which differences mattered.

Recap

In this course, you learned to:

• prepare a safe setting for an assistant: a clean branch, baseline checks and a written scope;
• turn a request into a task brief with acceptance criteria, and the evidence for each;
• review a generated change line by line, and check its dependencies and how it handles data;
• debug from evidence: reproduce first, then a hypothesis, a test that fails, and the fix;
• deliver a change that you can explain, with its decisions and a pull request that a reviewer can check alone.

If you have not done one yet, choose a case study for the certificate: Fix a bug in an unfamiliar codebase or Upgrade a dependency safely.