[1.0 T1] Pilot recommendation-first design and define the flow contract #177

Problem and outcome

Prove that retained reasoning improves design and human understanding without repeated interruptions before adding lifecycle or retrieval infrastructure.

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

• Run a small observed pilot in fresh Claude Code and Codex sessions using existing records. Include initial product framing without a prewritten direction note. No new schema, lifecycle engine, or full site redesign is prerequisite.

• Cover an authorized consequential feature, routine fix, repository-owned designer change, and genuine unresolved human choice. Compare with 0.3 and record both successes and failures.

• Define the contract: automatically use relevant reasoning, explain proportionally, recommend a path, continue within agreed intent, ask only for consequential unresolved judgment, and update the model at natural boundaries.

• Specify the optional brief distilled from expressed intent, stable goal anchors where useful, and the distinction between intended direction and current behavior. No strategy workshop or brief is required to start work.

• Count forced pauses, repeated questions, context size, duplicate rationale, and attention/time cost. Observe whether a person can understand and challenge the design; do not infer fluency from silence.

• Produce a proceed/narrow/defer recommendation and revise downstream scope from evidence. Confirm release wording later; keep FluencyLoop and proposed 1.0.

• Pilot the first substantial plan and feature without a prewritten product brief. Use partially specified intent with a missing audience, outcome, or exclusion that changes design; also include a fully specified request.

• Before dependent design, recommend a framing and ask only consequential unanswered product questions in one batch. Reuse answers already in the request; the agent writes the agreed brief at the normal artifact boundary rather than asking the person to fill a template.

• Include later work that reuses the established direction, a novel product fork that warrants a focused question, and evidence at closure/review that warrants a recommended direction revision.

Acceptance criteria

• Pilot evidence predates T2 infrastructure and includes baseline cost and interruption observations.

• An authorized feature proceeds after a concise recommendation without a separate proposal-approval exchange.

• Absent direction or unknown familiarity does not automatically stop the routine/designer cases.

• A genuine unresolved choice receives a recommendation and clear question; dependent work waits for an answer.

• The report states what machinery is justified or deferred and sets pilot-based thresholds for full evaluation.

• An unseeded first substantial plan/feature resolves a material product gap before selecting the dependent design; the question includes a recommendation grounded in expressed intent.

• A fully specified request and later session reusing its agreements do not trigger repeated audience/outcome/exclusion questions or a second approval of the faithful brief.

• An absent brief alone, init, and a routine fix trigger no product questionnaire; the report distinguishes useful product questions from avoidable interruptions.

• The pilot covers all three moments: initial framing, later unresolved product fork, and evidence-backed revision recommendation.

Validation

Use person-neutral seeded artifacts and observed agent sessions, with a short human assessment of design relevance and understanding. Preserve failures. This is an early behavior pilot, not a documentation-only contract task or a new runtime build.

Do not seed every run with an already-completed direction note. Compare incomplete versus sufficient user intent, verify the consequential question precedes dependent design, and test cross-session reuse plus a later new fork. Observe an evidence-based revision recommendation separately from a stale-document warning.

Starting points

README.md, MANIFESTO.md, docs/fluencyloop/constitution.md, PLAN_0_3.md; plugins/fluencyloop/skills/{plan,feature}/SKILL.md

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: T1
• Relative size: M (not a calendar estimate)
• Depends on: None; start here.
• Milestone: https://github.com/baokhang83/fluencyloop/milestone/3
• Plan: draft source
• Planning PR: docs: propose FluencyLoop 1.0 shared product direction and design #189