Skip to content

docs(docs): add status / implemented / outstanding table to audits README #1590

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Skords-01 merged 1 commit into from
May 4, 2026
Merged

docs(docs): add status / implemented / outstanding table to audits README #1590

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 50 additions & 14 deletions docs/audits/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,63 @@
# Audits

> **Last validated:** 2026-05-02 by @Skords-01. **Next review:** 2026-07-31.
> **Last validated:** 2026-05-04 by @Skords-01. **Next review:** 2026-07-31.
> **Status:** Active

Періодичні аудити коду, архітектури та UX.
Періодичні аудити коду, архітектури та UX. Цей README — навігаційний індекс
із status-таблицею; кожен аудит сам по собі — окремий документ із власним
freshness-маркером (див. `scripts/check-tech-debt-freshness.mjs`).
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Use the docs freshness checker path/process here, not the tech-debt checker.

These lines currently point to scripts/check-tech-debt-freshness.mjs, but docs freshness enforcement is wired through scripts/docs/check-freshness.mjs / docs-freshness.yml. This makes the Process section misleading.

Suggested doc fix 
-freshness-маркером (див. `scripts/check-tech-debt-freshness.mjs`).
+freshness-маркером (див. `scripts/docs/check-freshness.mjs`).

-- CI freshness-gate (`scripts/check-tech-debt-freshness.mjs`) форсить
-  `Last validated:` маркер ≤ 60 днів. PR падає, якщо маркер старший за
-  поріг — re-validate сторінку (статуси, лічильники, нові аудити) і
-  онови дату.
+- CI freshness-gate (`scripts/docs/check-freshness.mjs`) перевіряє покриття
+  freshness-заголовків для markdown-доків, а nightly/PR dry-run валідовує
+  актуальність маркерів. Якщо документ прострочений — перевалідуй сторінку
+  (статуси, лічильники, нові аудити) і онови дату.

Also applies to: 59-62

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/audits/README.md` at line 8, Replace the incorrect tech-debt freshness
checker path in the README: update any references to
scripts/check-tech-debt-freshness.mjs to the docs freshness checker
scripts/docs/check-freshness.mjs and mention the docs-freshness.yml workflow
where the Process section describes enforcement; ensure you update all
occurrences (including the other instance around lines 59-62) and adjust the
Process wording to reference the docs checker script and the docs-freshness.yml
CI workflow instead of the tech-debt checker.


## Lifecycle

- **Active** — аудит або трекер усе ще використовується для прийняття рішень / пріоритизації.
- **Closed** — оцінка завершена, fixes винесені у tracker (зазвичай — `*-implementation-roadmap.md` або `UX-IMPROVEMENT-PLAN.md`); сам документ лишається як historical record.
- **Archived** — аудит застарів і фізично переміщений у `docs/audits/archive/`. Канонічні правила тепер живуть у `docs/design/*` або `docs/governance/*`.

## Як читати таблицю

`Implemented` / `Outstanding` — coarse-grain лічильники recommended-items
у документі. Числа — приблизні («≈»), бо різні аудити форматують
рекомендації по-різному (топ-9, скоринг, секційні гаптики, P0/P1/P2-теги).
Точні per-item статуси завжди живуть у самому документі або у пов'язаному
`*-implementation-roadmap.md`. Реакомпуляція цих лічильників — раз на
квартал під час `Last validated` бампу.

## Документи

| Документ | Опис | Status |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------- |
| [`2026-04-26-sergeant-audit-devin.md`](./2026-04-26-sergeant-audit-devin.md) | Незалежний аудит Devin (historical record) | Closed |
| [`2026-04-28-sergeant-comprehensive-audit.md`](./2026-04-28-sergeant-comprehensive-audit.md) | Комплексний генеральний аудит | Closed |
| [`2026-04-28-implementation-roadmap.md`](./2026-04-28-implementation-roadmap.md) | План реалізації покращень | Active |
| [`2026-05-02-doc-hygiene-audit.md`](./2026-05-02-doc-hygiene-audit.md) | Doc-hygiene аудит — структура, freshness, dead code | Active |
| [`2026-05-03-readme-gap-analysis.md`](./2026-05-03-readme-gap-analysis.md) | README gap analysis — що відсутнє у root README | Active |
| [`UX-UI-AUDIT-2026.md`](./UX-UI-AUDIT-2026.md) | UX/UI аудит 2026 | Closed |
| [`UX-IMPROVEMENT-PLAN.md`](./UX-IMPROVEMENT-PLAN.md) | Технічний план покращення UX | Active |
| [`2026-05-03-ftux-onboarding-roast.md`](./2026-05-03-ftux-onboarding-roast.md) | Web FTUX onboarding roast — 6 P0 + 22 рекомендацій | Active |
| [`typography-2026-04-audit.md`](./typography-2026-04-audit.md) | Typography reference audit для Hard Rule #16 | Active |
| [`archive/ux-audit-2025.md`](./archive/ux-audit-2025.md) | UX-аудит 2025 | Archived |
| Документ | Опис | Status | Implemented | Outstanding | Tracker |
| -------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------- | ----------- | ----------- | -------------------------------------------------------------------------------------- |
| [`2026-04-26-sergeant-audit-devin.md`](./2026-04-26-sergeant-audit-devin.md) | Незалежний аудит Devin (historical record) | Closed | 30/31 | 1 | embedded таблиця у самому файлі |
| [`2026-04-28-sergeant-comprehensive-audit.md`](./2026-04-28-sergeant-comprehensive-audit.md) | Комплексний генеральний аудит | Closed | 12/18 ≈ | 6 ≈ | [`2026-04-28-implementation-roadmap.md`](./2026-04-28-implementation-roadmap.md) |
| [`2026-04-28-implementation-roadmap.md`](./2026-04-28-implementation-roadmap.md) | План реалізації покращень | Active | — | — | self |
| [`2026-05-02-doc-hygiene-audit.md`](./2026-05-02-doc-hygiene-audit.md) | Doc-hygiene аудит — структура, freshness, dead code | Active | 3/5 ≈ | 2 ≈ | embedded fix list |
| [`2026-05-03-readme-gap-analysis.md`](./2026-05-03-readme-gap-analysis.md) | README gap analysis — що відсутнє у root README | Active | 0/8 ≈ | 8 ≈ | self |
| [`UX-UI-AUDIT-2026.md`](./UX-UI-AUDIT-2026.md) | UX/UI аудит 2026 | Closed | — | — | [`UX-IMPROVEMENT-PLAN.md`](./UX-IMPROVEMENT-PLAN.md) |
| [`UX-IMPROVEMENT-PLAN.md`](./UX-IMPROVEMENT-PLAN.md) | Технічний план покращення UX | Active | — | — | self |
| [`2026-05-03-ftux-onboarding-roast.md`](./2026-05-03-ftux-onboarding-roast.md) | Web FTUX onboarding roast — 6 P0 + 22 рекомендацій | Active | 0/6 P0 ≈ | 6 P0 ≈ | self |
| [`archive/ux-audit-2025.md`](./archive/ux-audit-2025.md) | UX-аудит 2025 | Archived | n/a | n/a | superseded by [`UX-UI-AUDIT-2026.md`](./UX-UI-AUDIT-2026.md) |

## Diagnostics (ad-hoc deep-dives)

Окремий жанр від періодичних аудитів — `docs/diagnostics/` тримає
точкові «прожарки», які роблять fresh second opinion на конкретний
зріз системи й завершуються коротким roadmap'ом. Лінкаються звідси,
бо часто породжують нові tracker-items для активних аудитів.

| Документ | Опис | Status | Implemented | Outstanding |
| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------- | ----------- | ----------- |
| [`../diagnostics/2026-05-03-web-deep-dive/`](../diagnostics/2026-05-03-web-deep-dive/) | Web deep-dive — 18-item roadmap (forms, state, security, observability, DevX) | Active | 5/18 | 13 |

Comment on lines +46 to +49
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Add a Tracker column to the diagnostics table for schema consistency.

The main table defines where outstanding work is tracked, but diagnostics rows currently have no tracker field, which weakens the “single source of truth” goal.

Suggested table adjustment 
-| Документ                                                                                     | Опис                                                                                | Status   | Implemented | Outstanding |
-| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------- | ----------- | ----------- |
-| [`../diagnostics/2026-05-03-web-deep-dive/`](../diagnostics/2026-05-03-web-deep-dive/)       | Web deep-dive — 18-item roadmap (forms, state, security, observability, DevX)       | Active   | 5/18        | 13          |
+| Документ                                                                                     | Опис                                                                                | Status   | Implemented | Outstanding | Tracker |
+| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------- | ----------- | ----------- | ------- |
+| [`../diagnostics/2026-05-03-web-deep-dive/`](../diagnostics/2026-05-03-web-deep-dive/)       | Web deep-dive — 18-item roadmap (forms, state, security, observability, DevX)       | Active   | 5/18        | 13          | self    |
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
| Документ | Опис | Status | Implemented | Outstanding |
| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------- | ----------- | ----------- |
| [`../diagnostics/2026-05-03-web-deep-dive/`](../diagnostics/2026-05-03-web-deep-dive/) | Web deep-dive — 18-item roadmap (forms, state, security, observability, DevX) | Active | 5/18 | 13 |
| Документ | Опис | Status | Implemented | Outstanding | Tracker |
| -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------- | ----------- | ----------- | ------- |
| [`../diagnostics/2026-05-03-web-deep-dive/`](../diagnostics/2026-05-03-web-deep-dive/) | Web deep-dive — 18-item roadmap (forms, state, security, observability, DevX) | Active | 5/18 | 13 | self |
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@docs/audits/README.md` around lines 47 - 50, The diagnostics table lacks a
"Tracker" column; update the markdown table header row to add a "Tracker" column
and add a corresponding value for the diagnostics row
(`../diagnostics/2026-05-03-web-deep-dive/`) so the row becomes consistent with
the rest of the main table (update the header separator line and the row entry
to include the new Tracker cell with the appropriate tracker link or label).

## Process

- При злитті PR-у, що закриває recommendation з аудиту:
1. Оновити inline статус усередині самого документа (taglines типу `— done #PR`).
2. Бампнути `Implemented` лічильник у таблиці вище.
3. Якщо це закриває all-items → перевести Status у `Closed` і вказати tracker.
4. Якщо документ повністю superseded — перенести у `archive/` і додати
посилання на правонаступника в колонці Tracker.
- CI freshness-gate (`scripts/check-tech-debt-freshness.mjs`) форсить
`Last validated:` маркер ≤ 60 днів. PR падає, якщо маркер старший за
поріг — re-validate сторінку (статуси, лічильники, нові аудити) і
онови дату.
- Для нових аудитів використовуй шаблон з `docs/audits/UX-UI-AUDIT-2026.md`
(front-matter блок зверху + Lifecycle-status + явний tracker).
4 changes: 2 additions & 2 deletions docs/diagnostics/2026-05-03-web-deep-dive/00-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Web deep-dive — Overview

> **Last validated:** 2026-05-03 by @Skords-01.
> **Last validated:** 2026-05-04 by @Skords-01.
> **Status:** Active
> **Scope:** `apps/web` + `apps/server` + `packages/*` (mobile — лише дотичні точки).
> **Related:**
Expand Down Expand Up @@ -83,7 +83,7 @@
| 4 | Module prefetch on hover + on-idle | 3 | 1 | 3.00 | [03 §5.2 + §10.4](./03-backend-and-performance.md) — done (idle + connection gate) |
| 5 | `<DataState>` wrapper | 4 | 2 | 2.00 | [01 §3.2](./01-frontend-ergonomics.md) |
| 6 | `localStorage` 17 → 0 codemod | 4 | 2 | 2.00 | [02 §2.2](./02-architecture-and-state.md) |
| 7 | Audit docs status-table + archive >6-mo | 2 | 1 | 2.00 | [04 §8.5](./04-security-observability-testing-devx.md) |
| 7 | Audit docs status-table + archive >6-mo | 2 | 1 | 2.00 | [04 §11](./04-security-observability-testing-devx.md) — done (Status / Implemented / Outstanding) |
| 8 | Form-engine unification | 5 | 3 | 1.67 | [01 §3.1](./01-frontend-ergonomics.md) |
| 9 | CloudSync split-brain integration tests | 5 | 3 | 1.67 | [02 §2.3](./02-architecture-and-state.md) |
| 10 | C4-mermaid діаграми | 3 | 2 | 1.50 | [04 §9.2](./04-security-observability-testing-devx.md) |
Expand Down
4 changes: 3 additions & 1 deletion .../diagnostics/2026-05-03-web-deep-dive/04-security-observability-testing-devx.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Web deep-dive — Security, observability, testing & DevX

> **Last validated:** 2026-05-03 by @Skords-01.
> **Last validated:** 2026-05-04 by @Skords-01.
> **Status:** Active
> **Scope:** PII у логах, Sentry↔requestId correlation, CSP, contract тести, mutation testing, Storybook, C4-діаграми, CHANGELOG, Hard Rules registry, agent onboarding, audit docs status.
> **Related:** [`00-overview.md`](./00-overview.md), `docs/audits/`, `docs/security/`, `docs/agents/`.
Expand Down Expand Up @@ -332,6 +332,8 @@ OK.

## 11. Audit docs status table

> **2026-05-04 update.** `docs/audits/README.md` тепер має суцільну таблицю Status / Implemented / Outstanding / Tracker для всіх живих файлів + ad-hoc діагностик секцію. Додано «Як читати таблицю» + «Process» (CI freshness + quarterly recompilation). Більше не треба шукати по гіту, чи аудит ще актуальний.

**Що бачу.** `docs/audits/*` має 8+ файлів, але без status-індикатора («Active», «Implemented», «Superseded»). Reader не знає, чи це актуальна gap-list, чи історія.

**Recommendation.**
Expand Down
Loading