docs: improve readme files

10_Tennis/README.md

@@ -4,11 +4,19 @@
 
 <https://github.com/emilybache/Tennis-Refactoring-Kata>
 
-## The problem
+## Problem Statement
 
-Imagine you work for a consultancy company, and one of your colleagues has been doing some work for the Tennis Society. The contract is for 10 hours billable work, and your colleague has spent 8.5 hours working on it. Unfortunately he has now fallen ill. He says he has completed the work, and the tests all pass. Your boss has asked you to take over from him. She wants you to spend an hour or so on the code so she can bill the client for the full 10 hours. She instructs you to tidy up the code a little and perhaps make some notes so you can give your colleague some feedback on his chosen design. You should also prepare to talk to your boss about the value of this refactoring work, over and above the extra billable hours.
+You are taking over a tennis scoring system project from a colleague who:
 
-<https://en.wikipedia.org/wiki/Tennis_scoring_system>
+- Has spent 8.5 hours of a 10-hour billable project
+- Claims the work is complete with passing tests
+- Is currently unavailable due to illness
+
+Your manager has requested you to:
+
+1. Spend the remaining billable time (~1 hour) improving the code
+2. Prepare feedback on the current design
+3. Be ready to discuss the value of refactoring beyond billable hours
 
 ## Your task
 

1_FizzBuzz/README.md

@@ -2,8 +2,8 @@
 
 - Write a function that takes a number and returns it as a string.
 - For multiples of three return "fizz" instead of the stringified number.
-- For the multiples of five return “buzz" instead of the strigified number.
-- For numbers which are multiples of both three and five return “fizzbuzz" instead of the stringified number.
+- For multiples of five return "buzz" instead of the stringified number.
+- For numbers which are multiples of both three and five return "fizzbuzz" instead of the stringified number.
 
 ## Examples
 
@@ -21,15 +21,15 @@
 | **10**    | "buzz"     |
 | **11**    | "11"       |
 | **12**    | "fizz"     |
-| **13**    | "14"       |
-| **14**    | "15"       |
+| **13**    | "13"       |
+| **14**    | "14"       |
 | **15**    | "fizzbuzz" |
 
-## Folow TDD rules stryctly
+## Follow TDD rules strictly
 
-1. Write production code only to pass a single failing unit test.
-2. Write no more of a unit test than sufficient to fail (compilation failures are failures).
-3. Write no more production code than necessary to pass the one failing unit test.
+1. ✅ Write production code only to pass a failing unit test
+2. ✅ Write only enough of a unit test to make it fail
+3. ✅ Write only enough production code to make the failing test pass
 
 ## Great habits
 

20_Katacombs/katacombsAPI.yml

@@ -1,8 +1,8 @@
 openapi: 3.0.0
 info:
-  description: This API allows playing a text based adventure game
+  description: This API allows playing a text-based adventure game called Katacombs
   version: 1.0.0
-  title: Katacombs
+  title: Katacombs API
   license:
     name: Apache 2.0
     url: https://www.apache.org/licenses/LICENSE-2.0.html
@@ -28,7 +28,11 @@ paths:
               $ref: "#/components/schemas/Player"
       responses:
         "201":
-          description: Game started
+          description: Game started successfully
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Player"
     get:
       tags:
         - Game
@@ -58,12 +62,15 @@ paths:
             $ref: "#/components/schemas/Sid"
       responses:
         "200":
-          description: Game finished
+          description: Game finished successfully
           content:
-            text/plain:
+            application/json:
               schema:
-                type: string
-                example: Game Over
+                type: object
+                properties:
+                  message:
+                    type: string
+                    example: "Game Over"
         "404":
           description: Player with Sid playerSid not found
   /player/items/{itemSid}:
@@ -137,7 +144,15 @@ paths:
             $ref: "#/components/schemas/Action"
       responses:
         "200":
-          description: Action performed
+          description: Action performed successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                    example: "Action completed successfully"
         "404":
           description: Player or Item with Sid playerSid not found
         "405":
@@ -297,7 +312,7 @@ components:
           items:
             $ref: "#/components/schemas/Item"
     Player:
-      description: Player type
+      description: Player information
       type: object
       required:
         - sid
@@ -307,7 +322,11 @@ components:
           $ref: "#/components/schemas/Sid"
         name:
           type: string
-          example: Pedro
+          example: "Pedro"
+        location:
+          $ref: "#/components/schemas/Location"
+        bag:
+          $ref: "#/components/schemas/Bag"
     Sid:
       description: Sid type
       type: string

2_LeapYear/README.md

@@ -2,9 +2,9 @@
 
 Write a function that returns true or false depending on whether its input integer is a leap year or not.
 
-- A leap year is defined as:
+- A leap year is defined as one that:
 
-  - one that is divisible by 4
+  - is divisible by 4
   - but is not otherwise divisible by 100
   - unless it is also divisible by 400.
 
@@ -34,12 +34,12 @@ Write a function that returns true or false depending on whether its input integ
 | **1900**  | false      |
 | **2000**  | true       |
 
-## Folow TDD rules stryctly
+## Follow TDD rules strictly
 
-1. Write production code only to pass a failing unit test.
-2. Write no more of a unit test than sufficient to fail (compilation failures are failures).
-3. Write no more production code than necessary to pass the one failing unit test.
+1. ✅ Write production code only to pass a failing unit test
+2. ✅ Write only enough of a unit test to make it fail
+3. ✅ Write only enough production code to make the failing test pass
 
 ## Resources
 
-TestDesiderata by Kent Beck: <https://kentbeck.github.io/TestDesiderata>
+- [TestDesiderata](https://kentbeck.github.io/TestDesiderata) by Kent Beck

3_Fibonacci/README.md

@@ -1,28 +1,51 @@
-# Fibonacci kata
-
-- Write a function to generate the Fibonacci number for the nth position.
-  - Example: int Fibonacci(int position)
-- First Fibonacci numbers in the sequence are: 0, 1, 1, 2, 3, 5, 8, 13, 21, 34
-
-| **Input** | **Output** |
-| --------- | ---------- |
-| **0**     | 0          |
-| **1**     | 1          |
-| **2**     | 1          |
-| **3**     | 2          |
-| **4**     | 3          |
-| **5**     | 5          |
-| **6**     | 8          |
-| **7**     | 13         |
-| **8**     | 21         |
-| **9**     | 34         |
-
-## Folow TDD rules stryctly
-
-1. Write production code only to pass a failing unit test.
-2. Write no more of a unit test than sufficient to fail (compilation failures are failures).
-3. Write no more production code than necessary to pass the one failing unit test.
+# Fibonacci Kata
+
+## Problem Description
+
+Write a function that returns the Fibonacci number at a given position.
+
+### Function Signature
+
+```typescript
+function fibonacci(position: number): number;
+```
+
+### Sequence Definition
+
+The Fibonacci sequence is defined where each number is the sum of the two preceding ones, starting from 0 and 1.
+
+### Examples
+
+The first 10 Fibonacci numbers are:
+
+| Position | Value |
+| -------- | ----- |
+| 0        | 0     |
+| 1        | 1     |
+| 2        | 1     |
+| 3        | 2     |
+| 4        | 3     |
+| 5        | 5     |
+| 6        | 8     |
+| 7        | 13    |
+| 8        | 21    |
+| 9        | 34    |
+
+## TDD Rules
+
+1. ✅ Write production code only to pass a failing unit test
+2. ✅ Write only enough of a unit test to make it fail
+3. ✅ Write only enough production code to make the failing test pass
+
+## Suggested Test Cases
+
+1. Test position 0 returns 0
+2. Test position 1 returns 1
+3. Test position 2 returns 1
+4. Test larger positions (e.g., 8 returns 21)
+5. Test negative positions (should handle edge case)
 
 ## Resources
 
-TestDesiderata by Kent Beck: <https://kentbeck.github.io/TestDesiderata>
+- [Test Desiderata by Kent Beck](https://kentbeck.github.io/TestDesiderata)
+- [Fibonacci Sequence on Wikipedia](https://en.wikipedia.org/wiki/Fibonacci_number)

4_StackKata/README.md

@@ -1,24 +1,35 @@
-# Stack kata
+# Stack Kata
 
-- Implement a Stack class with the following public methods:
-  - `push(value: number) : void`
-  - `pop() : number`
-- Stack should throw an exception if popped when empty.
+## Requirements
 
-| **push** | **pop** |
-| -------- | ------- |
-| --       | throw   |
-| 1        | 1       |
-| 2        | 2       |
-| 1, 2     | 2, 1    |
-| 1, 2, 3  | 3, 2, 1 |
+Implement a Stack class with the following public methods:
 
-## Folow TDD rules stryctly
+- `push(value: number): void` - Adds a value to the top of the stack
+- `pop(): number` - Removes and returns the top value from the stack
+- The stack should throw an exception when attempting to pop from an empty stack
 
-1. Write production code only to pass a failing unit test.
-2. Write no more of a unit test than sufficient to fail (compilation failures are failures).
-3. Write no more production code than necessary to pass the one failing unit test.
+## Test Cases
+
+| Input (push) | Expected Output (pop) |
+| ------------ | --------------------- |
+| Empty Stack  | throws Exception      |
+| push(1)      | 1                     |
+| push(2)      | 2                     |
+| push(1,2)    | 2, then 1             |
+| push(1,2,3)  | 3, then 2, then 1     |
+
+## TDD Rules
+
+1. ✅ Write production code only to pass a failing unit test
+2. ✅ Write only enough of a unit test to make it fail
+3. ✅ Write only enough production code to make the failing test pass
+
+## Additional Guidelines
+
+- Follow the "Red-Green-Refactor" cycle
+- Keep tests and production code as simple as possible
+- Commit after each successful test
 
 ## Resources
 
-TestDesiderata by Kent Beck: <https://kentbeck.github.io/TestDesiderata>
+- [TestDesiderata by Kent Beck](https://kentbeck.github.io/TestDesiderata)

5_RomanNumerals/README.md

@@ -3,7 +3,7 @@
 ## First run
 
 - Implement a Roman numeral converter.
-- The code must be able to take numbers up to 3999 and convert to their roman equivalent.
+- The code must be able to take numbers up to 3999 and convert to their Roman equivalent.
 
 | **Arabic number** | **Roman numeral** |
 | ----------------- | ----------------- |
@@ -38,45 +38,51 @@
 | **2000**          | MM                |
 | **3000**          | MMM               |
 
+## Follow TDD rules strictly
+
+1. ✅ Write production code only to pass a failing unit test
+2. ✅ Write only enough of a unit test to make it fail
+3. ✅ Write only enough production code to make the failing test pass
+
 ## Second run
 
-Use the Transformation Priority Premise table to evolve your code.
+Use the Transformation Priority Premise (TPP) to evolve your code.
 
 ### TPP table
 
-| #   | Transformation               | Start code         | End code                                 |
-| --- | ---------------------------- | ------------------ | ---------------------------------------- |
-| 1   | {} -> nil                    | {}                 | [return] nil                             |
-| 2   | Nil -> constant              | [return] nil       | [return] “1”                             |
-| 3   | Constant -> constant+        | [return] “1”       | [return] “1” + “2”                       |
-| 4   | Constant -> scalar           | [return] “1” + “2” | [return] argument                        |
-| 5   | Statement -> statements      | [return] argument  | [return] min(max(0, argument), 10)       |
-| 6   | Unconditional -> conditional | [return] argument  | if(condition) [return] 1 else [return] 0 |
-| 7   | Scalar -> array              | dog                | [dog, cat]                               |
-| 8   | Array -> container           | [dog, cat]         | {dog=”DOG”, cat=”CAT”}                   |
-| 9   | Statement -> tail recursion  | a + b              | a + recursion                            |
-| 10  | If -> loop                   | if(condition)      | loop(condition)                          |
-| 11  | Statement -> recursion       | a + recursion      | recursion                                |
-| 12  | Expression -> function       | today – birth      | CalculateBirthDate()                     |
-| 13  | Variable -> mutation         | day                | var Day = 10; Day = 11;                  |
+| #   | Transformation              | Start code         | End code                                 |
+| --- | --------------------------- | ------------------ | ---------------------------------------- |
+| 1   | {} → nil                    | {}                 | [return] nil                             |
+| 2   | nil → constant              | [return] nil       | [return] "1"                             |
+| 3   | constant → constant+        | [return] "1"       | [return] "1" + "2"                       |
+| 4   | constant → scalar           | [return] "1" + "2" | [return] argument                        |
+| 5   | statement → statements      | [return] argument  | [return] min(max(0, argument), 10)       |
+| 6   | unconditional → conditional | [return] argument  | if(condition) [return] 1 else [return] 0 |
+| 7   | scalar → array              | dog                | [dog, cat]                               |
+| 8   | array → container           | [dog, cat]         | {dog="DOG", cat="CAT"}                   |
+| 9   | statement → tail recursion  | a + b              | a + recursion                            |
+| 10  | if → loop                   | if(condition)      | loop(condition)                          |
+| 11  | statement → recursion       | a + recursion      | recursion                                |
+| 12  | expression → function       | today – birth      | calculateBirthDate()                     |
+| 13  | variable → mutation         | day                | var day = 10; day = 11;                  |
 
 Transformations at the top of the list have priority over those at the bottom. It is better (or simpler) to change a constant into a variable than it is to add an `if` statement. So when making a test pass, favor simpler transformations (top of the list) over those more complicated (bottom of the list).
 
 Another way to use the Transformation Priority Premise is to keep writing new code using obvious implementation. Whenever duplication is detected, refactor to the next transformation to remove it. When refactoring, first try to use a simpler one. That does not always work; sometimes, you must move to a more complicated transformation or a mix of both.
 
 ### Example using Transformation Priority Premise on Fibonacci sequence
 
-| Input | Expected output | Transformation               | Implementation                                                          |
-| ----- | --------------- | ---------------------------- | ----------------------------------------------------------------------- |
-| 0     | 0               | {} -> nil                    | :warning: Does not work                                                 |
-| 0     | 0               | Nil -> constant              | `return 0`                                                              |
-| 1     | 1               | Constant -> scalar           | `return index`                                                          |
-| 2     | 1               | Unconditional -> conditional | `if number < 2 then return index else return index - 1`                 |
-| 3     | 2               | Unconditional -> conditional | No change                                                               |
-| 4     | 3               | Unconditional -> conditional | No change                                                               |
-| 5     | 5               | Scalar -> array              | `var fibs = [0, 1, 1, 2, 3, 5]; return fibs[index]`                     |
-| 6     | 8               | Scalar -> array              | `var fibs = [0, 1, 1, 2, 3, 5, 8]; return fibs[index]`                  |
-| 7     | 13              | Scalar -> array(duplication) | `var fibs = [0, 1, 1, 2, 3, 5, 8, 13]; return fibs[index]`              |
-| 8     | 21              | Statement -> tail recursion  | `if index < 2 return index else return fib(index - 1) + fib(index - 2)` |
+| Input | Expected output | Transformation              | Implementation                                                          |
+| ----- | --------------- | --------------------------- | ----------------------------------------------------------------------- |
+| 0     | 0               | {} → nil                    | :warning: Does not work                                                 |
+| 0     | 0               | nil → constant              | `return 0`                                                              |
+| 1     | 1               | constant → scalar           | `return index`                                                          |
+| 2     | 1               | unconditional → conditional | `if number < 2 then return index else return index - 1`                 |
+| 3     | 2               | unconditional → conditional | `if number < 2 then return index else return index - 1` NO CHANGE       |
+| 4     | 3               | unconditional → conditional | `if number < 2 then return index else return index - 1` NO CHANGE       |
+| 5     | 5               | scalar → array              | `var fibs = [0, 1, 1, 2, 3, 5]; return fibs[index]`                     |
+| 6     | 8               | scalar → array              | `var fibs = [0, 1, 1, 2, 3, 5, 8]; return fibs[index]`                  |
+| 7     | 13              | scalar → array(duplication) | `var fibs = [0, 1, 1, 2, 3, 5, 8, 13]; return fibs[index]`              |
+| 8     | 21              | statement → tail recursion  | `if index < 2 return index else return fib(index - 1) + fib(index - 2)` |
 
 The Transformation Priority Premise aims to evolve code while keeping complexity under control.