diff --git a/README.md b/README.md index 9444786..332faeb 100644 --- a/README.md +++ b/README.md @@ -89,6 +89,7 @@ service setup-команды проекта; он намеренно не пер | [Brownfield adaptation protocol](docs/brownfield-adaptation-protocol.md) | Для evidence-backed адаптации существующего репозитория до и после установки Memory Bank | | [Greenfield adaptation protocol](docs/greenfield-integration-protocol.md) | Для копирования шаблона, извлечения project facts из README и docs, адаптации Memory Bank и создания initial PRD | | [Использование Memory Bank](docs/usage.md) | Для повседневной работы с задачами и AI-агентами после внедрения | +| [Праймеринг контекста](docs/context-priming.md) | Для подготовки AI-агента к конкретной задаче и сбора релевантного контекста | | [Использование `memory-bank-cli`](docs/memory-bank.md) | Для пользователей CLI и downstream CI | | [Глоссарий](docs/glossary.md) | Термины governance и структуры документации, используемые в этом репозитории | | [Ownership и безопасные обновления](docs/ownership.md) | Для понимания lock schema, границ владения и conflict policy | diff --git a/docs/context-priming.md b/docs/context-priming.md new file mode 100644 index 0000000..26ebfd8 --- /dev/null +++ b/docs/context-priming.md @@ -0,0 +1,106 @@ +# Праймеринг контекста + +Праймеринг контекста (*context priming*) — подготовка агента к конкретной +задаче до начала планирования или изменения файлов. Агент последовательно +собирает ровно те сведения о проекте, предметной области, ограничениях и +текущем состоянии кода, которые нужны для обоснованной работы. + +Цель праймеринга — не «залить в модель весь репозиторий», а дать ей надёжную +исходную картину. Он уменьшает риск неверных предположений, повторения уже +принятых решений и изменений в неподходящей части системы. + +## Из чего состоит + +Практичный праймеринг проходит в три шага: + +1. **Общий прогрев.** Агент читает входную точку проекта и его навигацию: + `README`, инструкции агента и главный индекс Memory Bank. Так он узнаёт + назначение проекта, его устройство и правила работы. +2. **Специализация.** Агент переходит только к разделам, связанным с задачей: + конкретной подсистеме, доменному правилу, feature package, ADR, контракту + или тестовой политике. +3. **Граундинг задачи.** Перед планированием агент сверяет сформулированную + задачу с реальным состоянием репозитория: затронутым кодом, тестами, + интерфейсами и актуальными ограничениями. Результатом должны стать + подтверждённые факты, открытые вопросы и границы изменения. + +Для нового проекта первый шаг часто сводится к брифу и базовым инженерным +правилам. Для существующего проекта все три шага особенно важны: фактическое +состояние кода может отличаться от ожиданий или устаревшего описания. + +## Праймеринг в lifecycle Memory Bank + +В шаблоне праймеринг разделён на три уровня, чтобы не смешивать сбор контекста +с выбором lifecycle или выполнением задачи: + +- **P0 — route classification:** перед Task Routing собираются только facts, + нужные для выбора flow или точного вопроса человеку; +- **P1 — route profile:** после routing контекст специализируется под первый + gate выбранного flow — например, reproduction для bug fix или baseline для + refactoring; +- **P2 — execution grounding:** только когда конкретный flow требует + дополнительной проверки текущего состояния перед execution. В Feature Flow + это `GRND-*` evidence против immutable commit SHA перед sequencing. + +Подробный contract и profiles определяет +[`memory-bank/flows/priming.md`](../template/memory-bank/flows/priming.md). +Routing и праймеринг различаются: первый выбирает lifecycle, второй снабжает +следующее решение проверяемым контекстом. + +## Progressive disclosure, а не полная загрузка + +Праймеринг использует [progressive disclosure](../template/memory-bank/dna/principles.md): +сначала индекс, затем нужный раздел, затем конкретный документ или фрагмент. +Полный Memory Bank и весь репозиторий редко нужны для одной задачи; лишний +контекст затрудняет поиск существенного и делает ответ менее сфокусированным. + +Хорошая инструкция не перечисляет все возможные файлы, а задаёт маршрут и +цель чтения. Например: + +```text +Изучи README и главный индекс Memory Bank. Затем найди документы и код, +относящиеся к <подсистеме>. Не изменяй файлы. Сначала верни: +- текущую реализацию и её ограничения; +- применимые доменные и инженерные правила; +- существующие тесты и контракты; +- неясности, которые нужно уточнить до плана. +``` + +Аннотированные ссылки в индексах помогают агенту выбрать следующий документ: +они объясняют не только *что* открыть, но и *зачем* это читать. + +## Как сохранить чистый рабочий контекст + +Длинный разговор смешивает утверждённые решения, отклонённые варианты и +промежуточные догадки. Поэтому полезно: + +- собирать согласованный бриф или краткое резюме вне диалога; +- для следующей итерации начинать с чистого запроса, содержащего только + подтверждённые требования и результат праймеринга; +- отделять исследование, реализацию и независимую проверку в разные задачи + или сессии, когда им нужны разные точки зрения. + +Это не означает игнорировать историю: устойчивые решения следует фиксировать +в их canonical owner, а не держать только в переписке. + +## Минимальный результат праймеринга + +До перехода к плану или реализации агент должен уметь кратко ответить: + +- какую цель и границы имеет задача; +- какие документы и участки кода являются источниками истины; +- какие контракты, инварианты и тесты нельзя нарушить; +- чего пока не хватает для безопасного решения. + +Если остаётся существенная неопределённость, нужно уточнение или отдельный +research/design этап, а не уверенное продолжение реализации. Праймеринг не +заменяет Task Routing, acceptance criteria, планирование и проверку результата; +он делает каждый из этих этапов более обоснованным. + +## Связь с Memory Bank + +Memory Bank делает праймеринг повторяемым: его индексы и canonical documents +помогают агенту найти актуальный контекст без копирования описаний в каждый +промпт. Начинать следует с [`memory-bank/README.md`](../template/memory-bank/README.md), +а маршрут входящей задачи определяет +[`memory-bank/flows/routing.md`](../template/memory-bank/flows/routing.md). diff --git a/docs/glossary.md b/docs/glossary.md index b09876a..b2d1f95 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -79,6 +79,18 @@ SSoT, status и порядок зависимостей. Это удерживает верхний уровень читаемым и не смешивает обзор с низкоуровневыми подробностями. +## Context Priming (Праймеринг контекста) + +`Context priming` / `праймеринг контекста` — подготовка агента к конкретной +задаче через последовательный сбор релевантных project facts до планирования +или реализации. Обычно он включает общий прогрев по индексам проекта, +специализацию на нужной подсистеме и граундинг задачи на актуальном коде, +контрактах и тестах. Праймеринг следует `progressive disclosure`: он не +означает загрузить весь репозиторий или весь Memory Bank в один контекст. +Практическое описание приведено в [статье о праймеринге](context-priming.md). +В template lifecycle `P0` подготавливает выбор route, `P1` специализируется +под первый gate flow, а flow-specific `P2` выполняется только при необходимости. + ## Index-First `Index-first` — правило, по которому каждый документ должен быть достижим из diff --git a/template/memory-bank/flows/README.md b/template/memory-bank/flows/README.md index 9e4127b..0d568f6 100644 --- a/template/memory-bank/flows/README.md +++ b/template/memory-bank/flows/README.md @@ -6,6 +6,7 @@ purpose: Навигация по task routing, lifecycle flows и governed-ша derived_from: - ../dna/governance.md - routing.md + - priming.md - research.md - incident.md - bug-fix.md @@ -25,6 +26,7 @@ audience: humans_and_agents Каталог `memory-bank/flows/` содержит reusable process-layer для шаблона: lifecycle rules, taxonomy стабильных идентификаторов и governed templates. - [Task Routing](routing.md) — порядок выбора flow, routing predicates, повторный routing и Human Routing. +- [Task Context Priming](priming.md) — общий P0 перед routing и профильные P1-проверки контекста перед первым gate каждого route. - [Research & Discovery Flow](research.md) — evidence-backed lifecycle research-задач, от question framing до decision и handoff без преждевременного delivery. - [Incident And PIR Flow](incident.md) — containment, recovery, timeline, RCA, PIR и prevention work. - [Bug Fix Flow](bug-fix.md) — reproduction, analysis, fix, regression coverage и closure. diff --git a/template/memory-bank/flows/bug-fix.md b/template/memory-bank/flows/bug-fix.md index fffd83f..1dd922b 100644 --- a/template/memory-bank/flows/bug-fix.md +++ b/template/memory-bank/flows/bug-fix.md @@ -6,6 +6,7 @@ purpose: Delivery flow для воспроизводимого расхожде derived_from: - ../dna/governance.md - routing.md + - priming.md - ../engineering/testing-policy.md - ../engineering/validation-profiles.md canonical_for: @@ -23,6 +24,10 @@ audience: humans_and_agents Bug — наблюдаемое поведение, противоречащее уже принятому expected behavior. Источником может быть error tracker, support, QA, пользовательский report или incident analysis. +## Context Priming + +До Entry Gate выполни [`P1-BUG`](priming.md#p1-bug-bug-fix). Expected/actual behavior, reproduction evidence и unknowns фиксируются в bug report или linked delivery task. + ## Entry Gate - [ ] expected и actual behavior различимы diff --git a/template/memory-bank/flows/epic.md b/template/memory-bank/flows/epic.md index be643ae..94f3d3f 100644 --- a/template/memory-bank/flows/epic.md +++ b/template/memory-bank/flows/epic.md @@ -7,6 +7,7 @@ derived_from: - ../dna/governance.md - ../dna/frontmatter.md - routing.md + - priming.md - feature.md canonical_for: - epic_directory_structure @@ -36,6 +37,10 @@ FPF-основание: - **Evidence Graph**: epic решения должны ссылаться на источники, stakeholder answers, specs, ADR или code facts. - **Q-Bundle**: качество epic нельзя свести к одному score; оно проверяется набором отдельных свойств ниже. +## Context Priming + +До Epic Intake или Bootstrap Epic выполни [`P1-EPIC`](priming.md#p1-epic-epic). Intake facts и open questions принадлежат `brief.md`; при прямом bootstrap они фиксируются в `charter.md` или linked issue. + ## Package Rules 1. Все документы одного epic живут в `memory-bank/epics/EP-XXX/`. diff --git a/template/memory-bank/flows/feature.md b/template/memory-bank/flows/feature.md index 7ca4fd2..5b8f6a7 100644 --- a/template/memory-bank/flows/feature.md +++ b/template/memory-bank/flows/feature.md @@ -7,6 +7,7 @@ derived_from: - ../dna/governance.md - ../dna/frontmatter.md - routing.md + - priming.md - ../engineering/validation-profiles.md canonical_for: - feature_directory_structure @@ -35,6 +36,10 @@ audience: humans_and_agents Этот документ задает порядок появления feature-артефактов. Агент должен вести feature package по стадиям и не создавать downstream-артефакты раньше, чем созрел их upstream-owner. +## Context Priming + +До bootstrap feature package выполни [`P1-FEAT`](priming.md#p1-feat-feature). Он подготавливает problem-space context для draft `brief.md`, но не выбирает solution и не заменяет обязательный execution-grounding с immutable revision и `GRND-*` evidence перед Plan Ready. + ## Package Rules 1. Все документы одной фичи живут в `memory-bank/features/FT-XXX/`. diff --git a/template/memory-bank/flows/incident.md b/template/memory-bank/flows/incident.md index c0e7f4e..03b0312 100644 --- a/template/memory-bank/flows/incident.md +++ b/template/memory-bank/flows/incident.md @@ -6,6 +6,7 @@ purpose: Operational flow от обнаружения и containment инцид derived_from: - ../dna/governance.md - routing.md + - priming.md - ../engineering/testing-policy.md - ../ops/runbooks/README.md canonical_for: @@ -30,6 +31,10 @@ detection → triage → containment → recovery → timeline → root cause analysis → remediation → PIR → prevention work ``` +## Context Priming + +Сразу после route выполни timeboxed [`P1-INC`](priming.md#p1-inc-incident-and-pir). Его результат фиксируется в incident record/timeline; containment не ждёт broad discovery. + ## Response Gates - [ ] impact и affected surfaces зафиксированы diff --git a/template/memory-bank/flows/priming.md b/template/memory-bank/flows/priming.md new file mode 100644 index 0000000..63f1e16 --- /dev/null +++ b/template/memory-bank/flows/priming.md @@ -0,0 +1,149 @@ +--- +title: Task Context Priming +doc_kind: governance +doc_function: canonical +purpose: Общий контракт праймеринга контекста перед Task Routing и профильные P1-проверки перед первым gate каждого flow. +derived_from: + - ../dna/principles.md + - ../dna/governance.md + - routing.md +canonical_for: + - task_context_priming_contract + - route_priming_profiles + - priming_result_ownership +status: active +audience: humans_and_agents +--- + +# Task Context Priming + +Праймеринг контекста подготавливает агента к следующему решению; он не +выбирает lifecycle и не создаёт второй owner фактов. [`Task Routing`](routing.md) +выбирает flow, а этот документ определяет минимальные сведения, которые нужны +до routing и до первого gate выбранного flow. + +Праймеринг всегда применяет progressive disclosure: индекс → релевантный +раздел → конкретный owner-документ, код или evidence. Не загружай весь +репозиторий или весь Memory Bank, если следующий gate этого не требует. + +```text +task → P0: route classification → Task Routing + → P1: route profile → first flow gate + → P2: flow-specific execution grounding, если оно требуется +``` + +`P2` не является универсальным шагом. Например, Feature Flow сохраняет +execution-grounding с `GRND-*` против immutable commit SHA перед sequencing; +`P1-FEAT` не заменяет и не ослабляет это требование. + +## Common Contract + +### P0 Route Classification + +Выполни P0 после чтения startup-инструкций и до применения routing predicates: + +1. прочитай source task, report, alert или другой trigger и отдели stated facts + от предположений; +2. используй проектный индекс и routing rules, чтобы найти только facts, + необходимые для различения routes; +3. зафиксируй candidate route, evidence references, material unknowns и риск, + который может потребовать Human Routing; +4. не начинай implementation discovery, selected design или изменение файлов. + +P0 заканчивается сразу после того, как route обоснован либо сформулирован +точный вопрос для Human Routing. Признак incident прекращает broad discovery: +сразу выбери Incident Flow и продолжи его timeboxed `P1-INC`. + +### P1 Route Profile + +После Task Routing, но до первого meaningful gate выбранного flow, выполни его +P1-профиль. Каждый профиль задаёт: + +- purpose и минимальную область чтения; +- факты и unknowns, нужные следующему gate; +- canonical owner результата; +- stop condition, который не позволяет превратить праймеринг в скрытое + исследование или delivery. + +Не создавай отдельный `priming report`: результаты живут в уже существующем +owner-е route. В выводе всегда различай observed facts, источники и hypotheses. + +## Route Profiles + +### P1-INC Incident And PIR + +- **Собрать:** active impact, affected surfaces, доступные recovery signals, + релевантный runbook и, если это не задерживает containment, последний + deployment/change evidence. +- **Результат:** initial timeline/incident record фиксирует facts, owner и + containment options; hypotheses не выдаются за root cause. +- **Граница:** timebox discovery. Containment и human incident owner важнее + полного понимания системы. + +### P1-BUG Bug Fix + +- **Собрать:** canonical source expected behavior, observed actual behavior, + minimum reproduction inputs/environment и ближайшие existing tests или + evidence их отсутствия. +- **Результат:** bug report или linked delivery task различает expected/actual, + reproduction evidence и open uncertainty для Entry/Reproduction gates. +- **Граница:** не выбирай новый product behavior и не начинай refactoring. + +### P1-RES Research And Discovery + +- **Собрать:** decision question, decision owner, known evidence, relevant + access/privacy constraints, working assumptions и candidate stopping + condition. +- **Результат:** `research/R-XXX/brief.md` после bootstrap владеет question, + scope, assumptions, unknowns и stopping condition. +- **Граница:** не создавай delivery package, selected solution или committed + roadmap только из предположения. + +### P1-SMALL Small Change + +- **Собрать:** task intent/scope/acceptance, реально существующий reference + pattern, local change surface и known test/verify surface. +- **Результат:** Small Change routing record ссылается на проверенный pattern и + конкретные verify actions. +- **Граница:** если pattern не подходит, change surface не локален или нужны + design/plan/contract decisions, остановись и повтори Task Routing. + +### P1-REF Refactoring + +- **Собрать:** observable behavior и contracts, которые должны сохраниться, + baseline/characterization coverage, structural change surface и checkpoint + constraints. +- **Результат:** исходная task фиксирует preservation boundary, baseline и + material unknowns для Entry Gate. +- **Граница:** намеренное behavior/contract change не маскируй как + refactoring; верни его в Task Routing. + +### P1-EPIC Epic + +- **Собрать:** source/trigger, problem/outcome, rough scope/non-scope, + available evidence, stakeholders/decision owner, candidate slices и open + questions. +- **Результат:** `epics/EP-XXX/brief.md` при Intake владеет proposal facts; + при достаточных facts `charter.md` получает canonical intent. +- **Граница:** не создавай accepted subissues, delivery feature packages, + roadmap waves или code-level plan до соответствующих Epic gates. + +### P1-FEAT Feature + +- **Собрать:** relevant upstream PRD/epic/use case/ADR, applicable domain and + engineering rules, affected contracts and a bounded view of current + repository surfaces. +- **Результат:** draft `features/FT-XXX/brief.md` получает problem-space facts, + assumptions, constraints и unresolved decisions; он не принимает selected + solution. +- **Граница:** не подменяй `P2` execution-grounding. Перед Plan Ready всё ещё + требуются immutable revision и `GRND-*` evidence по current code/test state. + +### P1-HUMAN Human Routing + +- **Собрать:** competing routes, известные risk/approval trigger, missing fact + или product decision и минимальные evidence references. +- **Результат:** task формулирует точный вопрос человеку и последствия каждого + допустимого route. +- **Граница:** не проводи broad research и не продолжай delivery до решения; + после решения повтори Task Routing. diff --git a/template/memory-bank/flows/refactoring.md b/template/memory-bank/flows/refactoring.md index acaf194..90faf99 100644 --- a/template/memory-bank/flows/refactoring.md +++ b/template/memory-bank/flows/refactoring.md @@ -6,6 +6,7 @@ purpose: Behavior-preserving flow для локального, исследов derived_from: - ../dna/governance.md - routing.md + - priming.md - ../engineering/testing-policy.md - ../engineering/validation-profiles.md canonical_for: @@ -29,6 +30,10 @@ Refactoring меняет внутреннюю структуру, сохраня - **Research:** исследование структуры и вариантов; результатом может быть proposal, plan или ADR без production change. - **Systemic:** большой change surface, несколько компонентов или этапов, обязательные plan и checkpoints. +## Context Priming + +До Entry Gate выполни [`P1-REF`](priming.md#p1-ref-refactoring). Task фиксирует preservation boundary, baseline/characterization coverage и material unknowns до structural work. + ## Entry Gate - [ ] цель и non-goals сформулированы diff --git a/template/memory-bank/flows/research.md b/template/memory-bank/flows/research.md index 97eccd6..53c1d7f 100644 --- a/template/memory-bank/flows/research.md +++ b/template/memory-bank/flows/research.md @@ -7,6 +7,7 @@ derived_from: - ../dna/governance.md - ../dna/frontmatter.md - routing.md + - priming.md canonical_for: - research_directory_structure - research_lifecycle @@ -22,6 +23,10 @@ audience: humans_and_agents Research & Discovery Flow управляет задачей, чьим первым outcome является не delivery, а evidence-backed answer для named decision owner. **Discovery** — подходящее имя product-oriented режима этого flow, но не заменяет общий термин `research`: market research, technical spike и desk research могут не быть product discovery. +## Context Priming + +До bootstrap выполни [`P1-RES`](priming.md#p1-res-research-and-discovery). После bootstrap его question, known evidence, assumptions, unknowns и stopping condition принадлежат `brief.md` research package. + ## Package Rules 1. Все документы одного исследования живут в `memory-bank/research/R-XXX/`. diff --git a/template/memory-bank/flows/routing.md b/template/memory-bank/flows/routing.md index 0137029..6fc43a6 100644 --- a/template/memory-bank/flows/routing.md +++ b/template/memory-bank/flows/routing.md @@ -23,6 +23,12 @@ audience: humans_and_agents Flow определяет организацию lifecycle, но не глубину проверки. После выбора route отдельно выбери один [`validation profile`](../engineering/validation-profiles.md) в canonical owner выбранного delivery flow. Profile не участвует в routing order и не заменяет flow; если его triggers выявили contract, rollout или другой scope, несовместимый с текущим route, примени обычные rerouting rules. +## Context Priming Before Routing + +До применения routing predicates выполни [`P0 Route Classification`](priming.md#p0-route-classification): собери минимальные facts, чтобы выбрать flow или сформулировать Human Routing question. P0 не является implementation discovery, design или отдельным lifecycle; он заканчивается, как только route обоснован. + +После выбора route выполни соответствующий [`P1` profile](priming.md#route-profiles) до первого meaningful gate выбранного flow. Профиль собирает только context, необходимый этому gate, и сохраняет результаты в уже существующем canonical owner. Он не заменяет flow-specific execution grounding: например, Feature Flow всё ещё требует `GRND-*` evidence до sequencing. + ## Routing Order Проверяй маршруты именно в этом порядке. `Small Change` — fast path перед ветками Epic, Refactoring и Feature, а не semantic type задачи. После него сначала отделяй multi-feature Epic и behavior-preserving Refactoring, затем направляй оставшуюся single-delivery работу в Feature Flow. @@ -112,6 +118,8 @@ Issue / Task Следуй canonical triggers из [`../engineering/autonomy-boundaries.md`](../engineering/autonomy-boundaries.md). Для routing дополнительно запрашивай решение человека, когда выбор flow требует продуктового решения, риск нельзя контролировать существующими gates или несколько route остаются одинаково правдоподобными после доступного исследования. +Перед запросом человека выполни [`P1-HUMAN`](priming.md#p1-human-human-routing): зафиксируй competing routes, evidence, unknown или approval trigger и точный вопрос. Не продолжай delivery или broad research до решения; после него повтори Task Routing. + ## Outcome / Exit Contract ### Observable Outcome @@ -121,6 +129,7 @@ Issue / Task ### Required Evidence - issue/task или draft PR называет выбранный flow; для active incident достаточно alert или incident-management record, подтверждающего operational impact или необходимость containment; +- P0 evidence обосновывает выбранный flow; после routing P1 result находится в canonical owner выбранного flow, а не в отдельном priming report; - запись показывает, какие entry predicates сделали route допустимым; provisional incident record может быть дополнен полным routing record после containment; - для Epic route запись дополнительно указывает `Epic Intake`, когда facts ещё недостаточны для прямого `Bootstrap Epic`; - для Research route запись указывает decision question, decision owner и stopping condition; diff --git a/template/memory-bank/flows/small-change.md b/template/memory-bank/flows/small-change.md index 93a0bc4..d2c6cae 100644 --- a/template/memory-bank/flows/small-change.md +++ b/template/memory-bank/flows/small-change.md @@ -6,6 +6,7 @@ purpose: Прямой delivery flow для задач, где issue достат derived_from: - ../dna/governance.md - routing.md + - priming.md - ../engineering/testing-policy.md - ../engineering/validation-profiles.md canonical_for: @@ -23,6 +24,10 @@ audience: humans_and_agents `Small Change` — fast path, выбранный по predicates из [`routing.md`](routing.md). Для него не создаются feature package, `brief.md`, `design.md`, `implementation-plan.md` или ADR; issue/task остаётся owner-ом intent, scope и acceptance. +## Context Priming + +До Entry Gate выполни [`P1-SMALL`](priming.md#p1-small-small-change). Routing record ссылается на проверенный existing pattern и конкретные verify actions; если это невозможно, повтори Task Routing. + ## Entry Gate - [ ] Task Routing выбрал `Small Change`