Перейти к содержимому
Размах

F-16: lessons/ + decisions/ structure validated + sync script

Outcome

Foundation Week 4 завершён закладкой полной meta-структуры для process artifacts:

  • lessons/TEMPLATE.md — обновлён под канонический format (title/date/type/category/related/status), согласован с f02..f14 уже накопленными lessons
  • decisions/README.md + TEMPLATE.md — ADR pattern с P10 (минимум 3 альтернативы), Trade-offs, Reversal cost (обязательные секции)
  • decisions/ADR-001-razmakh-vps-isolation.md — sample local stub ADR с status: superseded указывающим на canonical в netnik-state/decisions/
  • scripts/sync-lessons.sh — bash, idempotent, dry-run support, content-aware (cmp -s before copy), optional —commit для netnik-state autostage

Verification: dry-run reports 0 copied/would-copy, 19 unchanged, 2 skipped — sync converged, double-storage (P16) maintained.

Что случилось (root cause)

P16 (Feedback capture & lessons) и P10 (минимум 3 альтернативы) — два из четырёх “процессных” принципов (с P14 / P24). До F-16 lessons писались ad-hoc, без enforced TEMPLATE; decisions жили только в netnik-state/decisions/ без local mirror; sync был manual cp + git.

Risk: при ускорении (Phase 1 → 1.5 → 2) — process artifacts деградируют первыми, что превращает P16 в lip-service. F-16 closure фиксирует convention BEFORE Phase 1 ships, когда правки структуры still cheap.

Fix applied

1. TEMPLATE.md канонизация

Старый TEMPLATE использовал phase/topic/tags/recorded_by frontmatter — но f02..f14 уже писали title/date/type/category/related/status. Расхождение между TEMPLATE и actual practice — anti-pattern.

Решение: обновил TEMPLATE под actual practice (frontmatter f02..f14 style). Добавил optional поля severity, tags для backwards compat. Body sections: Outcome / Root cause / Fix applied / What changes in process / Action items / Tracking (estimates-recalibration template) / Sources.

2. decisions/ structure

Convention zur Trennung major / local решений:

  • Major (stack choice, security, cross-tenant rules) → netnik-state/decisions/razmakh-<topic>-<date>.md (cross-project visibility для Netnik knowledge base)
  • Local (per-block tactical decisions) → razmakh/decisions/ADR-XXX-<topic>.md (sequential numbering, fast iteration)

Если local решение superseded by major из netnik-state — оставляем local stub с status: superseded + superseded_by: pointer. Example: ADR-001-razmakh-vps-isolation.md указывает на canonical netnik-state/decisions/razmakh-deployment-isolation-2026-05-17.md.

TEMPLATE требует:

  • P10: минимум 3 alternatives с pros/cons/verdict
  • Trade-offs: что теряем принимая решение
  • Reversal cost: матрица “когда (6 мес/1 год/2 года) → cost (low/medium/high) → why”
  • Point-of-no-return triggers: события после которых reversal становится prohibitive

3. sync script

scripts/sync-lessons.sh:

  • cmp -s content check (rsync —dry-run output parsing был flaky — заменил pre-check)
  • --dry-run mode для preview
  • --commit mode — git commit в netnik-state БЕЗ push (manual push когда готов)
  • Skip TEMPLATE.md / README.md / TAGS.md (infrastructure files)
  • Manual для Phase 1; cron entry комментарий для Phase 1.5

What changes in process going forward

  1. Каждый новый lesson — cp lessons/TEMPLATE.md lessons/<topic>-YYYY-MM-DD.md затем ./scripts/sync-lessons.sh (P16 двойное хранение enforced).
  2. Каждое новое решение — сначала classify (major → netnik-state vs local → razmakh/decisions), затем cp decisions/TEMPLATE.md. Убедиться что минимум 3 alternatives (P10) рассмотрены до acceptance.
  3. При supersession — старый ADR НЕ удаляем; меняем status: superseded + superseded_by: ссылка. Audit trail must быть intact.
  4. Cross-link convention: lessons/decisions/research linked through [[name]] syntax + frontmatter related: array. Один lesson → 1+ decision references; один decision → 1+ research references.

Action items

  • TEMPLATE.md updated под канонический format
  • decisions/README.md + TEMPLATE.md + ADR-001 sample
  • scripts/sync-lessons.sh с dry-run / —commit support
  • F-15 + F-16 inline ✅ DONE в plan/active/00-foundation.md
  • Sync run выполнен (19 unchanged — все existing lessons уже синканы)
  • Phase 1.5: добавить cron entry */15 * * * * scripts/sync-lessons.sh --commit + lefthook pre-commit lessons validation (frontmatter required fields check)
  • Phase 1.5: написать TAGS.md после ~20 lessons (стандартизировать tags vocabulary)
  • Phase 1.5: lefthook pre-commit hook — block commit если новый lessons/*.md не имеет related: field (минимум 1 link required)

Tracking

MetricPlannedActualVariance
F-16 plan0.5 дня (4 h)~1.5 h-62%
TEMPLATE.md update15 min10 min-33%
decisions/ structure30 min25 min-16%
sync-lessons.sh30 min40 min (rsync detection bug fix)+33%
Lessons writing (f15 + f16)30 min25 min-16%

Pattern from estimates-recalibration-2026-05-17.md holds — actual ~1.5h vs plan 4h ≈ divide by 2.5-3 for process tasks (less aggressive чем 6-8x для feature tasks, потому что process требует более careful crafting).

Sources

  • plan/active/00-foundation.md F-16 section (post-update)
  • lessons/TEMPLATE.md (new canonical version)
  • decisions/README.md (convention documented)
  • decisions/TEMPLATE.md (ADR format)
  • decisions/ADR-001-razmakh-vps-isolation.md (sample local stub)
  • scripts/sync-lessons.sh (idempotent sync utility)
  • Canonical reference for f02..f14 frontmatter style: lessons/f06-real-data-success-2026-05-17.md