Mentor review і remediation backlog

1. Робоче демо відповідає не на те запитання

Коли capstone уже показує робоче демо, дуже хочеться внутрішньо видихнути й вирішити, що далі будуть лише похвала, трохи оплесків і урочисте закриття ноутбука. На практиці все навпаки. Демо відповідає лише на запитання: «чи запускається проєкт». Mentor review — на доросле запитання: чи можна результату довіряти і чи розумієте ви, що зробили.

Тут корисна проста аналогія. Уявіть автомобіль, який чудово їде подвір’ям. Техогляд він цим ще не пройшов: фари світять криво, гальма хапають із затримкою, багажник закривається лише якщо стукнути долонею з правильним відчуттям моменту. Із проєктом так само. Сценарій працює, а review покаже слабке місце — у відтворюваності, перевірках, документації.

Mentor review потрібен не для того, щоб зловити вас на помилці, а щоб перевірити проєкт там, де поряд немає автора, який усе пояснить голосом. Mentor відкриває README.md, запускає проєкт, дивиться SPEC.md, читає EVIDENCE.md, оцінює перевірки, ставить запитання. Картина ясна — capstone дозрів. Ні — слабкі місця стали видимими.

flowchart TD
    A[Робоче демо] --> B[Mentor review]
    B --> C[Перевірка довіри]
    C --> D[Оцінювання за rubric]
    D --> E[REMEDIATION.md]

Зверніть увагу на важливу річ: review не скасовує захист — він його продовжує. На захисті ви розповідаєте, як мислите; на review mentor перевіряє, чи витримує ця логіка зустріч із кодом, тестами та обмеженнями.

На цьому етапі особливо добре видно проєкти, де автор занадто довірився Claude. Mentor запитує: «Звідки видно, що цей тест покриває основний сценарій?» — і одразу зрозуміло, чи був інженерний контроль, чи ви їхали на красивому AI-потоці в надії, що він сам довезе.

2. Ментор читає проєкт як історію рішень

Багато хто уявляє review як полювання на синтаксичні помилки: ось зараз mentor відкриє проєкт, знайде пару пропущених ком і, зітхнувши, піде в захід сонця. Насправді він дивиться значно ширше. Завдання — не «косяк заради косяка», а цілісна картина: наскільки проєкт чесний, відтворюваний і керований.

Якщо спростити, mentor майже завжди проходить по тих самих напрямах. Це не магія й не настрій дня — це продовження знайомої вам rubric.

Тепер давайте приземлимо це на наш приклад із CSV Validator. Демо працює: система валідує структуру та показує звіт про помилки. Mentor подивиться глибше. Що буде з порожнім CSV? Чому в SPEC.md обіцяно експорт, а в демо лише перегляд — і якщо експорт прибрали зі scope, чи є це в артефактах?

Ось тут і стає помітно, що review — це читання проєкту як історії рішень. Mentor відновлює ваш інженерний хід думки за файлами. Може відновити — capstone дорослий. Не може — проєкт здається крихким, навіть коли на екрані все красиво блимає й не падає.

Корисно пам’ятати ще одну річ: mentor не чекає ідеальності — він чекає чесності й керованості. Написали прямо, що edge case із порожнім датасетом не покритий, — зрілий сигнал. «Ну, мабуть, має працювати» — поганий. Різниця не в коді, а в інженерній позиції.

3. Розмова на review без випадів і паніки

Найчастіша проблема на review взагалі не технічна, а емоційна. Коли людина чує зауваження після довгої роботи, мозок любить реагувати як маленький особистий адвокат: «Зараз швидко поясню, чому це не проблема». Саме в цей момент розмова й псується.

Важливо пам’ятати просту річ: mentor review — це не суд над вашою особистістю. І не roast-session, хоча після третього зауваження іноді справді хочеться подивитися у вікно й задуматися про спокійне життя садівника. Код не ображається, файли не переживають — коментарі тут дані, а не напад.

Хороша розмова на review майже завжди будується навколо уточнення. Mentor каже, що перевірки слабкі, — не поспішайте з «але в мене ж 12 тестів»: кількість рідко щось доводить. Корисніше запитати, що саме бентежить: зв’язок тестів з основним сценарієм, непокритий edge case, відсутність smoke-check, неочевидний запуск, слабка прив’язка до SPEC.md. Розмова стає інженерною.

Нижче — дуже типовий приклад.

Ментор: Де видно, що ваші тести покривають основний сценарій, а не лише
дрібні функції навколо нього?

Погана відповідь:
"Ну я ж їх запускав, вони зелені."

Хороша відповідь:
"Зрозумів запитання. Зараз у `TEST_PLAN.md` у мене немає явного зв'язку тестів із кроками
основного сценарію. Отже, проблема не в кількості тестів, а в їх зв'язку
з demo-потоком. Це варто винести в доопрацювання."

Сильна відповідь на review майже завжди звучить спокійно й предметно. Ви не виправдовуєтеся — уточнюєте зміст зауваження, перевіряєте, чи правильно зрозуміли ризик, і думаєте, як це зафіксувати: правкою коду, дописаним README, оформленим обмеженням або перенесенням у Later.

Ще одна хороша навичка — не відповідати всім одразу «так, усе виправлю»: mentor чує не готовність до роботи, а розмивання пріоритетів. Сильніше розділити зауваження: це б’є по відтворюваності — Must fix, а це підсилює документацію — Should fix. Так ви керуєте змінами, а не киваєте.

4. Зауваження перетворюються на grading

Після review у багатьох виникає відчуття, що grading — таємнича математика: сім зауважень, мінус сім пунктів. На щастя, це не так. Оцінка в capstone — не диктант, де кожна помилка мінусує однаково, а загальна оцінка довіри до вашого результату.

Mentor дивиться на ті самі напрями rubric і збирає їх не в арифметику, а в картину. Один серйозний провал — проєкт неможливо запустити за README.md — важить сильніше за п’ять дрібних stylistic comments. І навпаки: кілька невеликих зауважень не ламають оцінку, якщо сценарій відтворюваний, обмеження чесно описані, evidence переконливий.

Дуже корисно дивитися на grading через порівняння типових ситуацій.

Тут якраз працює правило relevance over quantity, яке ви вже бачили. П’ять skills, три agents і один MCP server самі по собі оцінку не покращують. CSV Validator із хорошим CLAUDE.md, чітким task spec, невеликими diff і акуратними перевірками часто сильніший за проєкт, де навісили половину можливостей Claude Code просто тому, що вони є.

Дуже важливий нюанс: grading враховує не лише те, що вже виправлено, а й те, як ви мислите після зауважень: швидко зрозуміли зміст, класифікували ризик, сформулювали доопрацювання — сигнал зрілості. Тому не варто сприймати review як відбирання балів — правильніше бачити в ньому перевірку на чесність. Іноді саме завдяки йому видно: у вас акуратний, скромний, але зрілий capstone — цінніший за ефектний хаос.

5. Remediation backlog: керований план доопрацювань

Після хорошого review майже завжди накопичується набір зауважень. І ось тут легко зробити класичну помилку новачка — записати все в один список «доробити потім»: такі списки живуть недовго. Щоб цього не сталося, перетворіть зауваження на remediation backlog — пріоритизований список доопрацювань.

Тут допомагає дуже земна аналогія. Якщо тече дах, а ви водночас думаєте про новий колір штор, спочатку все-таки дах. Не тому, що штори не важливі, а тому, що важливий порядок. У backlog вистачає трьох кошиків.

Must fix

Should fix

Later

Окрема користь цієї схеми в тому, що вона не дає обіцяти неможливе. «Було б добре додати підтримку XLSX» — не тягніть у термінові правки: capstone захищався як мінімальний CSV-інструмент, отже, XLSX — чесний Later. А відсутність інструкцій із запуску — уже не Later: без них проєкт перестає бути відтворюваним.

Нижче — простий приклад REMEDIATION.md, який справді можна тримати в корені репозиторію поруч з іншими capstone-артефактами.

# REMEDIATION.md

## Must fix
- Указати версії Python і Node у `README.md`.
- Додати scenario-level test для порожнього CSV.

## Should fix
- Пов'язати тести з кроками основного сценарію в `TEST_PLAN.md`.
- Додати посилання на ключові коміти в `EVIDENCE.md`.

## Пізніше
- Підтримка XLSX.
- GitHub Actions для smoke-check.

Зверніть увагу на важливу деталь: хороші пункти backlog майже завжди конкретні. Не «покращити документацію», а «вказати версії Python і Node». Не «доопрацювати тести», а «додати scenario-level test для порожнього CSV». Конкретний запис можна перевірити; розмитий створює відчуття вічного боргу.

Ще корисніше — переводити зауваження в backlog з поясненням пріоритету. Це і є feedback loop: ви не просто чуєте критику, ви керуєте нею.

6. Фіксація review: щоб він не випарувався за годину

Навіть дуже хороший review марний, якщо вже до вечора ви не пам’ятаєте, що mentor мав на увазі під «слабким зв’язком тестів з основним сценарієм». Тому зауваження потрібно заземляти письмово — інакше пам’ять згладить формулювання, а backlog перетвориться на набір фраз, які через три дні ви розшифровуватимете як археолог.

Найзручніше тримати review у розділі Review log всередині REVIEW_NOTES.md або, якщо ведете все компактно, усередині EVIDENCE.md. Сенс не в назві, а в прив’язці зауважень до напрямів rubric — щоб не загубився контекст.

Ось як це може виглядати.

## Лог рев'ю

| Напрям        | Статус  | Коментар |
|---------------|---------|----------|
| Task spec     | strong  | `SPEC.md` чітко обмежує scope |
| Tests/checks   | weak    | Потрібен scenario-level test для порожнього CSV |
| Documentation  | medium  | Немає версій runtime у `README.md` |
| AI workflow    | medium  | Роль Claude описано, але без посилань на diff review |

Такий log одразу показує дві речі. По-перше, проєкт майже ніколи не буває «весь поганий» або «весь хороший». По-друге, review із маси зауважень перетворюється на карту проєкту: тут ви сильні, тут потрібен ремонт, тут достатньо уточнення.

Далі зв’язка працює просто. Зауваження з Review log або переходить у пункт REMEDIATION.md, або фіксується як accepted limitation: відсутність XLSX залишається в Later і одночасно записується в README.md як відома межа версії. Не кожне зауваження закінчується зміною коду — іноді достатньо чесно оформити обмеження й не видавати проєкт за те, чим він не є.

Коли зауваження спокійно розкладаються по Must fix, Should fix і Later, capstone звучить інакше — не як демо, якому пощастило доїхати до захисту, а як проєкт, яким керує розробник. Feedback перестає бути формальністю і стає частиною вашого інженерного почерку.

Але на цьому review-loop не закінчується. Винести з нього потрібно не «проєкту б ще доопрацювання», а конкретні Review log, REMEDIATION.md і accepted limitations — і повернути в артефакти: про запуск — у README.md і demo-path, про перевірки — у TEST_PLAN.md і EVIDENCE.md, про межі — у limitations і картку проєкту.