Tirsvad-Udemy-100_days_of_code/014-higher_lower
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Accept MIL-003 and add the Play a Game use case

Browse Source 
Create the use case chain for the game loop task: Use Case Diagram
UCD-001, User Stories US-001 (two stories), Use Case UC-001 and System
Sequence Diagram SSD-001, all Proposed. Link them from MIL-003.

Review MIL-003 (RC-006, Go) and accept it. Add the new artifacts to the
Traceability Matrix and register UCD, US, UC and SSD in the artifact
registry.

Refs #13
This commit is contained in:
Tirsvad
2026-10-04 23:41:35 +08:00
parent 64e3f04c6a
commit 923dde7dc9
8 changed files with 305 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/artifact-registry.md
+5 -1
View File
@@ -15,8 +15,12 @@ document of a type. `Primary File` may contain a glob (e.g.
| SA | Stakeholder Analysis | docs/stakeholder-analysis.md | 002 |
| PP | Project Plan | docs/project-plan.md | 002 |
| MIL | Milestone / Gateway | docs/milestones/*.md | 005 |
| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 006 |
| RC | SQA Review Record | docs/sqa/reviews/rc-*.md | 007 |
| TM | Traceability Matrix | docs/sqa/traceability-matrix.md | 002 |
| UCD | Use Case Diagram | docs/use-case-diagram.md | 002 |
| US | User Story | docs/user-stories.md | 002 |
| UC | Use Case | docs/uc-*/uc.md | 002 |
| SSD | System Sequence Diagram | docs/uc-*/ssd.md | 002 |
## Languages
docs/milestones/mil-003-console-game.md
+8 -3
View File
@@ -4,12 +4,13 @@
| Key | Value |
| --- | --- |
| ID | MIL-003 |
| CrossReference | [BC-001], [PP-001] |
| CrossReference | [BC-001], [PP-001], [US-001], [RC-006] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-04 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | [ddfe96f] |
| 2026-10-04 | Deprecated | Jens Tirsvad Nielsen | S01 | Initial version | [ddfe96f] |
| 2026-10-04 | Accepted | Jens Tirsvad Nielsen | S01 | Linked UC-001 and the user stories<br>Accepted after review RC-006 | pending |
---
@@ -43,6 +44,7 @@ An interactive console game started with `python -m higher_lower`, built on the
| Business Case objective / KPI / user story | Reference |
| --- | --- |
| O1, O3 | [BC-001] |
| US-001.01, US-001.02 | [US-001] |
## Ownership
@@ -60,7 +62,7 @@ An interactive console game started with `python -m higher_lower`, built on the
| # | Task | Summary | Needs its own Use Case/User Story? | Reference |
| --- | --- | --- | --- | --- |
| 1 | Implement display and input helpers | A function that prints the logo, "Compare A: ...", the `vs` art and "Against B: ..." using `format_data`, and one that asks for "A" or "B" and re-asks until valid (case-insensitive). Input and output go through injectable callables so tests need no real console. | No | |
| 2 | Implement the game loop | `play_game()` keeps the score, starts with a random pair, compares guesses with `check_answer`, moves B to A after a correct guess and picks a new B that differs from A. Prints the score after each round and "Sorry, that's wrong. Final score" at the end. | Yes | UC-001 Play a game (to be created with the SSD before this task starts) |
| 2 | Implement the game loop | `play_game()` keeps the score, starts with a random pair, compares guesses with `check_answer`, moves B to A after a correct guess and picks a new B that differs from A. Prints the score after each round and "Sorry, that's wrong. Final score" at the end. | Yes | [UC-001], [US-001] |
| 3 | Handle exhausted data | If every account has been used, end the game with a win message instead of failing to find a new B. | No | |
| 4 | Add entry point | `python -m higher_lower` runs `main()`, which calls `play_game()`; no side effects on import. | No | |
| 5 | Write game loop tests | pytest tests with scripted input and a seeded random generator: correct streak, wrong first guess, invalid input then valid, data exhausted, and the score printed. | No | |
@@ -71,3 +73,6 @@ An interactive console game started with `python -m higher_lower`, built on the
[PP-001]: ../project-plan.md
[MIL-002]: ./mil-002-game-logic.md
[ddfe96f]: https://git.tirsystem.com/Tirsvad-Udemy-100_days_of_code/014-higher_lower/commit/ddfe96ffa459d5e4b2e30d71bd53878aba2cfc5d
[US-001]: ../user-stories.md
[UC-001]: ../uc-001/uc.md
[RC-006]: ../sqa/reviews/rc-006-mil-003.md
docs/sqa/reviews/rc-006-mil-003.md
+46
View File
@@ -0,0 +1,46 @@
# SQA Review Record: MIL-003 Console game
## Metadata
| Key | Value |
| --- | --- |
| ID | RC-006 |
| CrossReference | [MIL-003], [QC-MIL-001] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-04 | Accepted | Jens Tirsvad Nielsen | S01 | Initial version | pending |
---
## Artifact Under Review
- Instance reviewed: [MIL-003]
- Checklist used: [QC-MIL-001]
## Checklist Results
| # | Criterion | Status | Evidence/Notes |
| --- | --- | --- | --- |
| 1 | A concrete deliverable is defined for every gate | Pass | A playable console game started with python -m higher_lower, with loop tests. |
| 2 | Explicit Go/No-Go criteria are stated for each gate | Pass | Six objectively checkable criteria. |
| 3 | Dependencies on other milestones are explicitly mapped (Optional) | Pass | Depends on MIL-002, with the reason. |
| 4 | Each milestone is traceable to a Business Case objective or KPI | Pass | O1, O3; stories US-001.01 and US-001.02. |
| 5 | Milestone owner and approving reviewer are identified | Pass | S01 and S01. |
| 6 | Milestone has a target date consistent with project constraints | Pass | 2026-10-12, inside the 2026-10-14 constraint in BC-001. |
## Overall Verdict
Go — all criteria pass. UC-001 and its SSD were created for task 2 (the game loop); UCD-001, US-001, UC-001 and SSD-001 stay Proposed until they are reviewed. MIL-004 stays Proposed. Reviewer and author are both S01: the project has a single participant, so the framework's author/reviewer separation cannot be met. S01 accepted this deviation when requesting acceptance (2026-10-04).
## Action Items
| Action | Owner | Due |
| --- | --- | --- |
| Review UCD-001, US-001, UC-001 and SSD-001 against their QC checklists | S01 | 2026-10-12 |
| Add UCD-001 and US-001 to the CrossReference of BC-001 and PP-001 when those documents are next edited | S01 | 2026-10-14 |
---
[MIL-003]: ../../milestones/mil-003-console-game.md
[QC-MIL-001]: ../../../framework/qc/qc-milestones-gateways.md
docs/sqa/traceability-matrix.md
+12 -4
View File
@@ -9,8 +9,8 @@
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-04 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | [a1ff735] |
| 2026-10-04 | Proposed | Jens Tirsvad Nielsen | S01 | Added RC-005 review of MIL-002 | [ee58fcd] |
| 2026-10-04 | Proposed | Jens Tirsvad Nielsen | S01 | Added RC-006 and the UC-001 artifacts | pending |
---
@@ -28,12 +28,16 @@ target is measurable. A row is added or updated whenever an artifact instance is
| [PP-001] | PP | [BC-001], [SA-001] | [MIL-001], [MIL-002], [MIL-003], [MIL-004] | [RC-003] |
| [MIL-001] | MIL | [BC-001], [PP-001] | - | [RC-004] |
| [MIL-002] | MIL | [BC-001], [PP-001], [MIL-001] | - | [RC-005] |
| [MIL-003] | MIL | [BC-001], [PP-001] | - | - |
| [MIL-003] | MIL | [BC-001], [PP-001], [MIL-002], [US-001] | [UC-001] | [RC-006] |
| [MIL-004] | MIL | [BC-001], [PP-001] | - | - |
| [UCD-001] | UCD | [SA-001], [BC-001] | [US-001], [UC-001] | - |
| [US-001] | US | [UCD-001], [BC-001], [MIL-003] | [UC-001] | - |
| [UC-001] | UC | [UCD-001], [US-001], [SA-001] | [SSD-001] | - |
| [SSD-001] | SSD | [UC-001] | - | - |
## Coverage Notes
- No use cases, user stories or design artifacts exist yet (UC-001 is planned for MIL-003).
- UCD-001, US-001, UC-001 and SSD-001 exist but are not reviewed yet. No domain model or design artifacts exist yet.
- `-` in Upstream means foundational; in Downstream, nothing is built on it yet; in Last Reviewed, no `RC-*` exists yet.
---
@@ -49,6 +53,10 @@ target is measurable. A row is added or updated whenever an artifact instance is
[RC-002]: ./reviews/rc-002-stakeholder-analysis.md
[RC-003]: ./reviews/rc-003-project-plan.md
[RC-004]: ./reviews/rc-004-mil-001.md
[a1ff735]: https://git.tirsystem.com/Tirsvad-Udemy-100_days_of_code/014-higher_lower/commit/a1ff73580fdcfad5bbb3854298fdfa0c16ada853
[RC-005]: ./reviews/rc-005-mil-002.md
[ee58fcd]: https://git.tirsystem.com/Tirsvad-Udemy-100_days_of_code/014-higher_lower/commit/ee58fcdc1c9c83b0721022d623e4989591a47987
[UCD-001]: ../use-case-diagram.md
[US-001]: ../user-stories.md
[UC-001]: ../uc-001/uc.md
[SSD-001]: ../uc-001/ssd.md
[RC-006]: ./reviews/rc-006-mil-003.md
docs/uc-001/ssd.md
+53
View File
@@ -0,0 +1,53 @@
# System Sequence Diagram: Play a Game
## Metadata
| Key | Value |
| --- | --- |
| ID | SSD-001 |
| CrossReference | [UC-001] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-04 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | pending |
---
## Source Use Case
[UC-001] Play a Game, main success scenario. The alternative flows (invalid answer, tie, no account left) are out of scope for this diagram.
## Diagram
```plantuml
@startuml
actor Player
participant ":System" as System
Player -> System : startGame()
System --> Player : accounts A and B
loop while the guess is right
Player -> System : makeGuess(choice)
System --> Player : right, score, new accounts A and B
end
Player -> System : makeGuess(choice)
System --> Player : wrong, final score
@enduml
```
## System Operations Table
| Step | Message (verb phrase) | Parameters | Return | Use case step |
| --- | --- | --- | --- | --- |
| 1 | startGame | none | accounts A and B | 1, 2 |
| 2 | makeGuess | choice (A or B) | right, new score, new accounts A and B | 3, 4, 5, 6 |
| 3 | makeGuess | choice (A or B) | wrong, final score | 3, 7 |
Steps 2 and 3 are the same operation; the loop shows the right-guess outcome repeating, and the last call shows the wrong-guess outcome.
## Lifecycle Notes
A game starts with `startGame` and ends when `makeGuess` returns wrong; the System keeps the score and the current accounts in between.
---
[UC-001]: ./uc.md
docs/uc-001/uc.md
+77
View File
@@ -0,0 +1,77 @@
# UC-001 Play a Game
## Metadata
| Key | Value |
| --- | --- |
| ID | UC-001 |
| CrossReference | [UCD-001], [US-001], [SA-001], [SSD-001] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-04 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | pending |
---
Format: Fully Dressed
## Scope
The Higher Lower console game.
## Level
User goal.
## Primary Actor
Player.
## Stakeholders and Interests
| Stakeholder | Interest |
| --- | --- |
| S01 | A correct game that shows good practice ([SA-001]) |
| S02 | Readable behaviour that matches the assignment ([SA-001]) |
## Preconditions
The Player has started the game.
## Postconditions (Success Guarantee)
The Player has seen the final score of the game.
## Main Success Scenario
1. The Player starts a game.
2. The System shows two different accounts, A and B.
3. The Player guesses which account has more followers.
4. The System tells the Player the guess was right, adds one to the score, and shows the new score.
5. The System makes the account the Player compared against the new A and shows a new B.
6. The Player repeats from step 3 until a guess is wrong.
7. The System tells the Player the guess was wrong and shows the final score.
## Extensions / Alternative Flows
- 3a. The Player gives an answer that is not a valid choice: the System asks again; the round does not change.
- 3b. Both accounts have the same number of followers: either choice counts as right.
- 5a. No account is left that differs from the current A: the System ends the game and shows the final score.
No `<<include>>` or `<<extend>>` use cases apply.
## Special Requirements / Business Rules
- Step 2 and 5: A and B are never the same account.
- Step 3b: equal follower counts make both choices right.
## Open Issues
None.
---
[UCD-001]: ../use-case-diagram.md
[US-001]: ../user-stories.md
[SA-001]: ../stakeholder-analysis.md
[SSD-001]: ./ssd.md
docs/use-case-diagram.md
+54
View File
@@ -0,0 +1,54 @@
# Use Case Diagram
## Metadata
| Key | Value |
| --- | --- |
| ID | UCD-001 |
| CrossReference | [SA-001], [BC-001], [US-001], [UC-001] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-04 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | pending |
---
## Purpose and Scope
The system boundary is the Higher Lower console game. One actor, the Player, uses it to play a game. Traces to [BC-001] objective O1 and to stakeholders S01 and S02 ([SA-001]), who play the game; S03 only reads the repository.
## Diagram
```plantuml
@startuml
left to right direction
actor Player <<Actor>>
rectangle "Higher Lower <<System>>" {
usecase "Play a Game" as PlayAGame
}
Player --> PlayAGame
@enduml
```
## Actor Table
| Actor | Stereotype | Stakeholder ID (SA) | Goals (use cases) |
| --- | --- | --- | --- |
| Player | Actor | S01, S02 | Play a Game |
## Use Case Table
| Use Case | Actor(s) | Goal |
| --- | --- | --- |
| Play a Game ([UC-001]) | Player | Guess, round after round, which of two accounts has more followers, and see the final score |
## Relationships
None: there is a single use case, so no `<<include>>` or `<<extend>>` is used.
---
[SA-001]: ./stakeholder-analysis.md
[BC-001]: ./business-case.md
[US-001]: ./user-stories.md
[UC-001]: ./uc-001/uc.md
docs/user-stories.md
+50
View File
@@ -0,0 +1,50 @@
# User Stories
## Metadata
| Key | Value |
| --- | --- |
| ID | US-001 |
| CrossReference | [UCD-001], [UC-001], [BC-001], [MIL-003] |
## Version History
| Date | Status | Author | Reviewer | Change | Commit |
| --- | --- | --- | --- | --- | --- |
| 2026-10-04 | Proposed | Jens Tirsvad Nielsen | S01 | Initial version | pending |
---
## Purpose and Scope
The stories for epic [MIL-003] (Console game): playing rounds and seeing the result. They support [BC-001] objective O1.
## Story List
### US-001.01 Guess which account has more followers
- **As a** Player, **I want** to guess which of two accounts has more followers and keep playing while I am right, **so that** I can build a streak.
- **Acceptance Criteria:**
- Given a new game, when it starts, then two different accounts A and B are shown.
- Given two accounts, when I guess the one with more followers, then my score goes up by one and the next round starts with that account as A and a new account as B.
- Given an invalid answer, when I submit it, then I am asked again and the round does not change.
- **Traces to:** [UC-001], [MIL-003]
- **Size:** one iteration.
### US-001.02 See my final score
- **As a** Player, **I want** to see my final score when the game ends, **so that** I know how well I did.
- **Acceptance Criteria:**
- Given a round, when I guess the account with fewer followers, then the game ends and shows my final score.
- Given every account has been used, when no new account can be shown, then the game ends and shows my final score.
- **Traces to:** [UC-001], [MIL-003]
- **Size:** one iteration.
## INVEST Check
Both stories are Independent of each other in wording, Negotiable in detail, Valuable to the Player, Estimable, Small (one iteration) and Testable through the acceptance criteria. No exceptions.
---
[UCD-001]: ./use-case-diagram.md
[UC-001]: ./uc-001/uc.md
[BC-001]: ./business-case.md
[MIL-003]: ./milestones/mil-003-console-game.md