28 lines
2.2 KiB
Markdown
28 lines
2.2 KiB
Markdown
# Reflection: Project-docs initialization and feature drift
|
|
|
|
- Task: `20260811-native-display-f2456ea9`
|
|
- Date: 2026-08-11
|
|
- Status: Confirmed workflow gap in this repository state
|
|
|
|
## What happened
|
|
|
|
The repository had no `.project-docs/` tree. The required initializer created the canonical templates before the feature task was claimed. The feature task then correctly limited its intentional documentation writes to its own task record and prefixed evidence/reflection records.
|
|
|
|
At completion, `check_doc_drift.py` compared the feature task's recorded base commit with the worktree. Because every initializer-created canonical template was still untracked, the script classified all of them as protected `FOREIGN_DOC` changes. A feature task cannot accept those paths, while removing them would leave a partial document system and violate the initialization contract.
|
|
|
|
## Why it matters
|
|
|
|
On a repository that first adopts this skill during an already dirty feature workflow, the documented sequence “initialize, then claim a feature task” cannot by itself produce a passing Task Documentation Gate unless the initialization tree is first established in a separate canonical baseline.
|
|
|
|
## Better workflow
|
|
|
|
Initialize `.project-docs/` in a serialized integration task and establish that tree as a reviewed repository baseline before starting feature work. If the initializer must run during feature intake, the tooling should provide an explicit, human-confirmed initialization ownership path rather than requiring agents to hide, delete, or manually reclassify protected files.
|
|
|
|
## Promotion candidate
|
|
|
|
- Target: `maintain-project-docs` initialization workflow and/or drift script.
|
|
- Proposal: add a first-install mode that atomically records initializer-owned canonical files, or explicitly require and guide a serialized initialization integration before feature task creation.
|
|
- Evidence: this task's drift output lists every initializer template as `FOREIGN_DOC` even though no feature agent edited those templates after initialization.
|
|
- Future impact: prevents completion deadlocks on repositories adopting the document system for the first time.
|
|
- Human confirmation: required before changing the shared skill or committing a new canonical documentation baseline.
|