[1.0 T6] Reconcile implementation and update review/backfill workflows #182

Problem and outcome

Keep the current model useful at natural completion boundaries without making documentation repair or repeated approval a delivery prerequisite.

Interaction contract

Keep FluencyLoop. Proposed positioning: Stay fluent as people and agents evolve the product.

Use retained product reasoning automatically. Explain consequential choices at the right depth. Recommend a path. Continue within agreed intent. Ask when human judgment is needed. Update the shared model at natural boundaries.

The flagship goal/principles/precedents/tradeoffs reasoning is integrated into the existing design explanation at proportional depth. It is not a mandatory recital, proposal form, or new approval exchange. People must remain able to understand and challenge the design.

Scope

• At existing feature/session completion, link the original rationale and record actual deviations and outcome. Distill once at wrap-up rather than generating another per-slice narrative.

• Update only affected concepts and material product/feature prose; mechanical views assemble links. Honor already-authorized direction changes without asking again.

• Surface unrelated stale documentation or missing links passively in handoff/site. Ask only if the underlying uncertainty changes the work; do not hold completion hostage to knowledge cleanup.

• Review explains actual product change and consequential reasoning. Backfill preserves reconstruction/uncertainty and never invents an original proposal, human approval, or historical vision.

• At a natural completion/review boundary, identify actual evidence that challenges an audience, outcome, exclusion, or other product assumption. Explain that evidence and recommend a specific direction revision; distinguish observed facts from product inferences.

• Ask for human judgment only when the revision is genuinely new and consequential. Honor an already-authorized revision without asking again; never silently turn an inferred revision into agreed direction.

• An unresolved direction recommendation is visible without blocking unrelated delivery. Do not reopen the whole vision for every review, stale reference, or changed timestamp; ask before dependent future design if the answer becomes necessary.

Acceptance criteria

• A changed implementation approach is reconciled once and the current design reflects the actual result.

• Unchanged rationale is reused, not independently re-summarized across outcome and review.

• A fetch/run contradiction affecting the change is corrected or explicitly reported; unrelated stale prose does not block delivery.

• No separate closure approval is required solely to finalize records.

• Backfill stays visibly reconstructed and shared records contain no private competence data.

• A review with evidence challenging a product assumption includes a specific, evidence-backed direction recommendation and requests only the new judgment it needs.

• A review without relevant new evidence does not initiate a recurring vision workshop; a stale-reference warning alone is insufficient.

• Already-authorized direction changes are applied without repeat confirmation, while unaccepted revisions remain explicitly proposed and do not block unrelated work.

Validation

Exercise closure/review/backfill with changed, unchanged, abandoned, and incomplete outcomes. Include an unrelated stale record and verify normal delivery continues. Test assembly/reference plumbing; observe interruption and duplication costs.

Add observed closure/review cases with a challenged audience/outcome assumption, no new product evidence, and an already-authorized revision. Verify the agent separates evidence from inference, preserves unresolved proposals honestly, and completes unrelated delivery without requiring a vision rewrite.

Starting points

plugins/fluencyloop/skills/{feature,review,backfill}/SKILL.md; claude-skills mirrors; scripts//assemble-pr-view.; distillations and tests/pr-view.bats

Constraints

• Target dev; main distributes releases. No runtime implementation occurs in the planning PR.

• T1 is an observed pilot using existing artifacts before new infrastructure. Use its evidence to retain, narrow, or defer later scope.

• Recommend and continue within authorized intent; ask with a recommendation only for consequential unresolved judgment. Batch independent questions, reuse settled answers, and wait for dependent work. Silence is not approval.

• Absent briefs, historical link gaps, stale prose, and unreviewed metadata alone are advisory. Do not require onboarding, cleanup, or retrospective approvals to work.

• Unknown familiarity is not fluency and does not automatically require a blocking probe/check. Support requested guided learning without quizzes; keep calibration/preferences private. T5 explicitly updates inherited pause rules.

• Capture rationale once, link mechanical views, record outcome deviations at natural closure, distill once at wrap-up, and reuse unchanged context.

• Preserve append-only history/provenance; Bash and PowerShell implement the same contract. Core remains Node-optional; no new database, hosted service, or vector search.

• No brief prerequisite does not waive resolving product uncertainty that determines design: establish enough direction early, reuse agreements, and reopen only for a material fork or relevant new evidence.

Dependencies and size

• Task: T6
• Relative size: M (not a calendar estimate)
• Depends on: T5: [1.0 T5] Recommend and continue within authorized intent in plan and feature workflows #181
• Milestone: https://github.com/baokhang83/fluencyloop/milestone/3
• Plan: draft source
• Planning PR: docs: propose FluencyLoop 1.0 shared product direction and design #189