Graduate the second-thoughts dev doc; retire the in-progress one#381
Merged
Conversation
Second thoughts (the reflex + the user-triggered refinement) has shipped, so per the in-progress doc rules it should stop reading as open work. Graduate the durable content into a permanent docs/dev/second-thoughts.md that describes current reality - the reflex/deliberation model, the pure-narrow reviewer, the non-reasoning model choice, the append refinement + acted <think> connective, the data model, contracts, interactions, and the load-bearing gotchas - with the deferred automatic-correction and emergent-loop extensions in a short "future work" section rather than a phased plan. Delete the migration-narrative in-progress doc (git keeps it). Add the feature to the dev README index next to intuition, and repoint the QA use-case's dev link at the permanent doc.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
SYNOPSIS
Second thoughts has shipped, so its
docs/dev/in-progress/doc should stop reading as open work. Graduate the durable content to a permanent feature doc and retire the migration narrative, per the in-progress doc rules inCLAUDE.md.PURPOSE
The in-progress doc was a 700-line phased plan ("v1 does X, phase 2 adds Y, phase 3 would..."), written while the feature was being built. Now that the reflex + the user-triggered refinement are live, that framing misleads: a future session reads it as active work with pending phases, when most of it has shipped and the rest is deliberately parked. A stale in-progress doc misleads with full confidence - worse than none.
DESCRIPTION
docs/dev/second-thoughts.md- a permanent feature doc in the standard shape (Role, reviewer, refinement, Files, Data model, Contracts, Interactions, Gotchas). Describes current reality, not change history: the reflex/deliberation model, the pure-narrow reviewer input contract, the non-reasoningmistral-smallchoice (with the reasoning-model failure captured as the lesson), the append refinement + the acted<think>connective, themark_second_thoughts_actedRPC, the conviction-hidden display gate, the realtime backfill, and the load-bearing gotchas (tool-URL provenance, permit-rejection, pure-reviewer-doubt-is-correct, ...).docs/dev/in-progress/second-thoughts.md(deleted; git preserves it).README.mdindex next to intuition, and repoint thechat-second-thoughtsQA use-case's dev link at the permanent doc.Docs-only.
mise run checkgreen (markdownlint + the full gate).Generated by Claude Code