Readmission Requirements

This is the assignment for First Step: the Requirements, and the first one, so it comes with a repository of your own:

$ dutchengineer get readmit_scorer
$ cd readmit_scorer
$ dutchengineer data pull

That is where you build for the rest of the course. The lessons walk through booking_scorer in front of you; every assignment lands here, and the project in the final week takes this same repository the whole distance. Like every assignment in this course, you submit by committing and pushing to it — the push is the submission, there is no separate upload. The bar at the bottom of this page is how you know it is ready.

What you will practice

This one produces docs/requirements.md in your readmit_scorer repository — the same seven sections, filled from a request nobody has scoped yet.

Working through it, you will:

• Screen the request first, and say in writing whether it needs a model at all.
• State what the hospital is trying to change, rather than what the model predicts.
• Name who confirms each line, and what each of them is actually agreeing to.
• Write the requirements in words a clinician can read without an engineer beside them.
• Write the out-of-scope list, and put the argument you expect to have into it.
• Say which numbers are open, who owns them, and when you need the answer.

The assignment

You have watched an entire notebook become a deployed application. Now do it yourself, on a second one — a readmission model in your readmit_scorer repository, with no walkthrough and nobody to ask. Every lesson from here pairs with one of these: the same work, the same order, on a notebook that will not behave the same way.

Start where the lesson started.

The setup rhymes with booking_scorer’s: a model that already exists, and a request to put it in front of people. The workflow behind it does not rhyme at all, and copying the booking requirements and swapping the nouns will produce a bad document.

In the booking scorer, the prediction automatically triggers an offer. In the readmission scorer, a care coordinator sees the score and remains responsible for the follow-up plan. That changes who owns the decision, what the product has to communicate, and where the model is allowed to sit in the workflow.

Build docs/requirements.md for that project using the same framework.

Pay attention to where the stakeholder map changes and where it stays the same. You will still need Product, the model owner, the data owner, and the application owner. But one of the owners here is clinical governance, and their rule is not a preference — the thread states it twice.

The healthcare context also has sharper boundaries. The course model and dataset are not validated for real clinical decisions. Your requirements should make that limitation explicit rather than allowing a demonstration system to sound like an approved decision-making system — the score prioritizes outreach, and your document should say who owns any change to that.

What you hand in

Commit to your readmit_scorer repository:

• docs/requirements.md — the screening answer, the goal in the hospital’s words, the requirement lines with an owner on each, the out-of-scope list, and the open decisions with names and dates.

The bar

You are ready when:

• The screening question is answered in writing, including what the answer would have to be for this not to need a model.
• The goal says what the hospital is trying to change, not what the model predicts. If the sentence would still be true with a different model in it, it is the goal.
• Every line has a name beside it, and each of those people is agreeing to something they could actually confirm.
• A clinician could read it without an engineer beside them — no term used before it is defined.
• The out-of-scope list contains the argument you expect to have, not only the things nobody wanted.
• The governance rule is stated as a limitation, with its owner: the score prioritizes outreach, and it is not validated for clinical decisions.

The exercise is complete when the two requirements documents look like they came from the same engineering process applied to two different products, not from the same template filled in twice.

Draft it here, part by part. The skeleton below is editable — click into it and replace each bracketed prompt with your own words, working section by section from the manager’s thread. Check runs the structural review: sections present, prompts replaced, owners named, the open-decisions table actually owned. It checks structure, never judgment — a passing document can still be a bad one, and the two tests above are still the real bar. When it passes, commit the document to your readmit_scorer repository as docs/requirements.md.

And make that commit the first of many: your repository is where every assignment deliverable in this course lands. The baseline, the project skeleton, the package, the tests, the contract, the migrations — each lesson adds its piece, committed as you go. By the end of the module the history reads like a real project, because it is one; the data and the model artifacts stay out of git, exactly as the lessons build it, and everything else is the record of what you shipped. And to be completely unambiguous about the mechanics: pushing that commit is how you hand the assignment in. Your repository is the submission — there is no separate upload, no form, nothing to attach.

# Readmission Scorer — Requirements

## Goal
[What is going wrong today, and what does the product change? State the
intended intervention — and the line the score is never allowed to cross.]

## Delivery
[What is the target, in whose words? Which earlier dates gate the serving
design and the launch? If the real date is not on paper, say so.]

## Stakeholders / Owners

| Area | Owner | Owns | Open with them |
|---|---|---|---|
| Product | [owner] | [what do they own?] | [what is still open with them?] |
| Model | [owner] | [what do they own?] | [what must you get before they leave?] |
| Consumers | [who uses the score?] | [both consumers, with the numbers from the thread in your README] | [what would change their day?] |
| Clinical Governance | [who?] | [what rule do they own, in their words?] | [who owns any change to that rule?] |

## Current State

### Product
Known: [what the thread in your README actually established]
Unknown: [what nobody answered]

### Model
Known: [what the handoff says]
Unknown: [what is merely said, not verified — and the question nobody
has asked about the number]

### Data
Known: [what Sam's notes promise]
Unknown: [what production will need that the thread never covered]

### Application
Known: [what exists today]
Unknown: [what you cannot know without the consumers' tooling]

## Decisions Made
[Only what the team has actually agreed to — each line traceable to a
person in the handoff — the thread, Sam's notes, or the notebook. If you
wrote it and
nobody said it, it belongs under Proposed / Assumed instead.]

## Proposed / Assumed
[Beliefs that have not been established. The biggest one is a number
everyone repeats and nobody has questioned.]

## Open Decisions

| Decision | Owners | Evidence needed | Due by |
|---|---|---|---|
| [the thing that blocks everything else] | [who] | [what will settle it] | [when it starts blocking] |

## V1 Requirements
[Requirements, not architecture. What must be true to call the first
version shipped? One bullet each.]

## Out of Scope for V1
[What is deliberately not in the first cut — including anything that is
prohibited rather than merely deferred.]

## Related Documents

- [System design](system-design.md) — [one line on what it covers, and who it is for]