Development Stuck-Point Session Analysis
Alignment status: review. This report analyzes local Claude and Codex user-message history to identify recurring ways projects get stuck during development and the practical moves that unstick them.
Table Of Contents
Method And Coverage
Explicit evidence: I parsed the full readable `~/.claude/history.jsonl` and `~/.codex/history.jsonl` files. I also scanned all available Codex rollout JSONL files for session metadata such as cwd, model, provider, and CLI version.
Prompt-count source: Codex compact history was used as the authority for Codex user-prompt counts. Rich rollout files were used for metadata and audited for user-message shape, but rollout user items beginning with skill blocks or injected instruction context were excluded from pattern counts to avoid contaminating the analysis.
| Source | Readable input | Parse errors | Normalized messages | Sessions | Date range |
|---|---|---|---|---|---|
| Claude | 10,019 history lines | 0 | 10,019 | 3,795 | 2025-12-10 to 2026-06-04 |
| Codex | 6,549 compact history lines plus 853,289 rollout lines | 0 | 6,549 | 2,560 | 2026-01-20 to 2026-06-04 |
Classification caveat: The pattern counts below are keyword-rule classifications and can overlap. They are reliable as directional stuck-point signals, not as exclusive labels for each prompt. Confidence rises where history counts, repeated prompt text, command usage, and `tasks/lessons.md` all point to the same failure mode.
Main Finding
Projects usually get stuck when the active work loses a trustworthy closure boundary. The same symptoms recur: the user asks what is next, asks to commit and push again, reports that a fix is still not visible, asks whether a skill is stale, or has to correct intent after the agent routes or implements past the requested boundary.
The root cause is rarely "one hard bug." It is usually one of four boundary failures: unclear worktree/shipping state, stale task truth, insufficient observable verification, or command/skill routing confusion. Frontend animation work amplifies all four because the defect is visual, stateful, and easy to misverify from code alone.
| Stuck signal | Message count | Session count | Explicit examples from history | Primary inference |
|---|---|---|---|---|
| Skill, pack, and routing confusion | 4,102 | 3,064 | `I tried restarting codex and I don't see access to the skills appearing as slash commands in codex`; `Is it because the skill is stale?` | Workflow machinery becomes part of the work, so product progress pauses while the runner, skill registry, or command convention is repaired. |
| Shipping and dirty-state loops | 3,808 | 2,828 | `commit and push` appears 496 times; `/ship` appears 1,538 times; `update docs, commit and push` appears 76 times. | Closure has to be manually reasserted because the agent often cannot prove what is done, staged, committed, pushed, or still dirty. |
| Task status drift | 1,894 | 1,399 | `what's next?` appears 107 times; `I see that the todo.md still references run instead of exec the new convention`. | Task docs remain useful but become stale candidates rather than authoritative truth unless reconciled against artifacts and git history. |
| Verification and build failures | 1,129 | 757 | `we still get a 500 error`; `there was an error trying to seed, can you run it and try to fix the error`. | Validation is often performed too late or from ambiguous output, which lets regressions reach the next phase. |
| Scope and intent corrections | 768 | 561 | `do not implement, just report`; `No that's not what I see`; `do not revert the y`. | The agent sometimes acts before separating report-only, destructive, visual, or semantic intent from implementation intent. |
| Frontend animation and visual UX regressions | 683 | 516 | `the close drawer animation has seriously regressed`; `the pack is facing the wrong direction`; `previous fixes are still not appearing`. | Code-level fixes are not enough when the acceptance criterion is a time-based visual state transition. |
Source Comparison
Claude history has more total prompts and older product-development loops. Codex history is more concentrated in skill, benchmark, and remediation workflows. This implies the stuck pattern has evolved from mostly product implementation closure to meta-workflow reliability and skill routing.
| Area | Claude evidence | Codex evidence | Interpretation |
|---|---|---|---|
| High-frequency closure commands | `/ship` 1,537; `/clear` 882; `/ship-end` 266; `/run` 182 | `$targeted-skill-builder` 93; `$benchmark-test-skill` 82; `$session-triage` 62; `$pack` 55 | Claude side shows repeated manual closing and context resets. Codex side shows more durable remediation and pack management. |
| Recent trend | Claude remains active in June with 175 messages. | Codex has 144 June messages and owns most current `tools/agentic-skills` remediation work. | The runner split itself is now part of the workflow surface; final handoffs must normalize slash vs dollar commands. |
| Correction memory | Correction examples often show product bugs, UX mismatches, and "what's next" loops. | Correction examples often show skill routes, alignment YAML, benchmark reviews, and stale skill visibility. | Use one shared evidence model, but route fixes to different owner surfaces depending on whether the blocker is app behavior or workflow behavior. |
Top Projects
| Rank | Project | Messages | Sessions | Share | Stuck-point read |
|---|---|---|---|---|---|
| 1 | apps/bismarck-v0.4 | 1,438 | 613 | 8.7% | Large implementation surface; high shipping and status-loop pressure. |
| 2 | poke/monorepo | 1,284 | 511 | 7.7% | Task/status and shipping loops across monorepo work. |
| 3 | tools/agentic-skills | 1,158 | 447 | 7.0% | Highest workflow-remediation density; skill routing, alignment pages, lessons, and verification dominate. |
| 4 | apps/lexcorp-war-room | 1,111 | 380 | 6.7% | Product plus operational workflow complexity. |
| 5 | experimental/metternich-engine | 1,084 | 381 | 6.5% | Visual/editor interaction work with UX and implementation uncertainty. |
| 6 | apps/bismarck-v0.3 | 929 | 228 | 5.6% | Runner/session/terminal reliability issues and repeated bug fix loops. |
| 7 | apps/loadoutworks.com | 839 | 316 | 5.1% | Early product planning, data/model evolution, and database verification. |
| 8 | dev/mobile-ideas | 535 | 316 | 3.2% | Idea-to-workflow routing and skill availability. |
| 9 | apps/pitwall-monorepo | 511 | 237 | 3.1% | Recent rich-menu visual regressions and investigation loops. |
| 10 | apps/lexcorp-sdk | 416 | 149 | 2.5% | Developer-tool workflow and packaging adoption questions. |
Recurring Stuck Patterns
1. Skill And Route Resolution Becomes The Work
4,102 messages3,064 sessions29 lesson headings
Evidence: `tools/agentic-skills` is the top project inside this category with 601 messages. Command counts include `$targeted-skill-builder` 93, `$benchmark-test-skill` 82, `$pack` 57, `/pack` 47, and `/investigate` 27. `tasks/lessons.md` has 29 headings classified as skill/pack/routing related.
`I tried restarting codex and I don't see access to the skills appearing as slash commands in codex`
`I see that the todo.md still references run instead of exec the new convention`
Why it sticks: When the command surface is stale, the agent cannot reliably start the right workflow. Work then shifts from product progress to resolving the runner, pack install, skill mirror, or slash/dollar naming problem.
Unstick move: Run a deterministic skill-health preflight before any multi-step workflow: resolve the intended command, check pack status, check active skill path, check mirror/version, and normalize final handoffs to the current runner.
2. Shipping Closure Requires Too Much Manual Reassertion
3,808 messages2,828 sessions`commit and push` 496 mentions
Evidence: `/ship` appears 1,538 times, `/ship-end` 266 times, `commit and push` 496 times, and `update docs, commit and push` 76 times. The most common closure transition involving meaningful categories is `task_status_drift -> shipping_dirty_state` with 157 adjacent occurrences and `shipping_dirty_state -> task_status_drift` with 147.
`can you examine all of the uncommited code and push them to github based on feature/purpose`
`update docs, commit and push`
Why it sticks: The user has to repeatedly ask the agent to close the loop because the agent's notion of done is not always tied to staged files, verification output, commit SHA, remote push state, and stale task cleanup.
Unstick move: Treat every mutation as unfinished until a ship boundary is explicit: intended files, excluded dirty files, validation command outputs, commit result, push result, and next command or `none`.
3. Task Docs Drift Away From Reality
1,894 messages1,399 sessions`what's next` 107 mentions
Evidence: Status prompts recur from December through June. A 2026-06-01 lesson explicitly says to verify stale unchecked tasks before recommending next work.
`can you validate that the work that has been labeled finish are actually finished and the work that is labeled outstanding or todo is still pending?`
`what's next?`
Why it sticks: The tracker is treated as a source of truth even after commits, generated artifacts, or prior alignment pages already satisfied the work. The user then has to ask for status, reconciliation, and next-step selection again.
Unstick move: Before choosing next work, reconcile task docs against git log, artifact existence, recent alignment pages, and review notes. Stale unchecked items should trigger reconciliation, not repeat work.
4. Verification Is Present But Sometimes Untrustworthy
1,129 messages757 sessions8 lesson headings
Evidence: `tasks/lessons.md` includes direct corrections about false pass claims, pre-existing failure proof, and commit/push return code verification. The history also contains recurring bug/error prompts such as `we still get a 500 error` and `there was an error trying to seed`.
`Never write a test/verification claim from remembered or garbled tool output`
`Prove a test failure is pre-existing before calling it unrelated`
Why it sticks: Verification runs happen, but when the output is ambiguous, stale, or not tied to the actual edited surface, the project can move forward on a false pass or misdiagnosed unrelated failure.
Unstick move: Prefer machine-readable reporters, focused tests at the owner surface, parent-commit reproduction for unrelated failures, and explicit "not yet verified" language when output is unclear.
5. Intent Gets Lost At Implementation Boundaries
768 messages561 sessions9 lesson headings
Evidence: Correction phrases include `do not implement` 16 times, `wrong` 40 times, and `still` 268 times. Lessons include scope confirmation for destructive work and interview language corrections.
`do not implement, just report`
`No that's not what I see.`
Why it sticks: The agent sometimes collapses analysis, planning, and implementation into one action, or treats a visual/product-language request as a code-state request. The result is extra work that has to be undone, clarified, or re-routed.
Unstick move: When the user says report-only, compare, audit, determine, or do not implement, freeze mutations except prompt/task tracking required by the current repo convention. For ambiguous visual feedback, restate the screen behavior in product language before changing code.
6. Visual And Animation Bugs Need Visual Proof, Not Just Code Proof
683 messages516 sessions9 lesson headings
Evidence: Recent examples concentrate in `tools/agentic-skills` and `apps/pitwall-monorepo` with drawer, card, rich-menu, and animation regressions.
`the close drawer animation has seriously regressed`
`previous fixes are still not appearing in the prototype page`
`the pack is facing the wrong direction`
Why it sticks: Visual regressions are stateful and timing-sensitive. A test can pass while the human-visible behavior is still wrong, and a dev-server/cache issue can make a correct code change appear absent.
Unstick move: Use a visual-debug contract for UI work: known-good comparator, dev-server freshness check, browser screenshot or trace, deterministic state timeline, and no shipping until the visual acceptance criterion is observed.
Workflow Sequences
Adjacent message transitions show where work tends to loop. Counts below are category-to-category transitions inside the same session after sorting by timestamp.
| Transition | Count | Interpretation | Unstick trigger |
|---|---|---|---|
| `task_status_drift -> shipping_dirty_state` | 157 | Status ambiguity often resolves into a ship request. | Ask for a status reconciliation before shipping, then ship exact intended files. |
| `shipping_dirty_state -> task_status_drift` | 147 | After shipping, next-work selection is still ambiguous. | Ship final answer should include verified next command or `none`, not stale task text. |
| `verification_build_failures -> shipping_dirty_state` | 123 | Fix/validation loops often end in a closure push. | Require machine-readable validation summary before commit. |
| `shipping_dirty_state -> verification_build_failures` | 95 | Closure sometimes exposes missed verification. | Move verification before staging and commit, not after. |
| `scope_intent_correction -> other` | 247 | Corrections frequently reset the conversation into fresh work. | Route corrections to lessons and owner contract updates, not just local fixes. |
| `verification_build_failures -> verification_build_failures` | 148 | Failure investigation can get trapped in repeated attempts. | After a repeated failure, switch to root-cause mode with reproduction, comparator, and smallest failing surface. |
Skill Performance Trends
`tasks/lessons.md` is direct correction evidence rather than inferred history. It contains 74 lesson headings. Rule classification of those headings produced 29 skill/pack/routing lessons, 19 alignment/research lessons, 9 scope/intent lessons, 9 frontend/animation lessons, 8 verification lessons, 7 shipping lessons, and 5 task-status lessons.
This means the highest-friction workflows are not one skill alone. The system gets stuck at the boundaries between skills: route selection, alignment page lifecycle, task truth, verification proof, and final command normalization.
| Visible skill signal | Count | Meaning |
|---|---|---|
| `$targeted-skill-builder` | 93 | Durable remediation is already the common Codex path for recurring workflow gaps. |
| `$session-triage` | 62 | Single incidents often need verified triage before a generalized fix. |
| `$pack` and `/pack` | 104 combined | Skill availability and pack install state are common blockers. |
| `$benchmark-test-skill` | 82 | Benchmarking is used as a validation surface for skill contract changes. |
| `/investigate` | 93 | Root-cause investigation is a reliable unstick move when repeated fixes fail. |
Unstick Playbook
When You Feel Stuck
Ask the agent for a stuck-state packet, not another broad next step. The packet should include current branch, dirty files split into intended/unrelated, last passing verification, last failing verification, current task source, artifact evidence, and the single suspected blocker.
When A Fix Is Still Wrong
Switch from execution to investigation. Require a reproduction, the expected behavior in product language, the observed behavior, a known-good comparator, and the smallest owner surface before any new fix.
When You Cannot See A Change
First verify environment freshness: dev server PID/port, build artifact timestamp, browser route, cache state, and a screenshot or DOM marker. Do not keep changing source until the displayed app is proven to be the edited app.
When The Agent Wants To Ship
Require a shipping boundary: intended changed files, excluded unrelated files, exact validation commands and results, commit SHA, push target, residual risk, and next command. If any line is unknown, shipping is not done.
When The Agent Recommends Next Work
Ask it to prove the task is still open from artifacts and git history. Unchecked task docs are candidates, not truth. If an alignment page or committed artifact already satisfies the task, reconcile the tracker first.
When Skill Commands Look Wrong
Run skill resolution before doing work: active runner command convention, installed pack status, visible skill path, mirror version, stale symlink/archive collision, and reload/fresh-session requirement.
Ranked Recommendations
| Rank | Pattern | Frequency evidence | Recommendation type | Suggested name and description | Likely owner surface | Validation expectation |
|---|---|---|---|---|---|---|
| 1 | Repeated stuck-state ambiguity across routing, status, verification, and visibility | Top stuck categories total thousands of overlapping signals; `still` 268, `what's next` 107, `commit and push` 496. | Skill/standing instruction | development stuck-state preflight and unstick routing: detect whether the blocker is status, visibility, verification, routing, or intent, then route to the smallest owner workflow. | Shared workflow conventions plus `exec`, `investigate`, `ship`, `ship-end`, and `session-triage` contracts. | Layer1 contract tests with fixtures for report-only, still-not-fixed, stale task, invisible change, and dirty-tree closure; one focused benchmark smoke. |
| 2 | Manual closure and dirty-tree reassertion | `/ship` 1,538; `/ship-end` 266; `commit and push` 496. | Skill contract hardening | ship boundary proof gate: one invariant checklist for intended files, unrelated dirty files, verification, commit result, push result, and next command. | `ship`, `ship-end`, `commit-and-push-by-feature`. | Layer1 fixture that rejects final answers without commit SHA, push target, validation result, and dirty-file classification. |
| 3 | Stale task truth and repeated next-work prompts | `what's next` 107; task-status category 1,894 messages; 2026-06-01 lesson about stale unchecked tasks. | Standing instruction plus helper script | task artifact reconciliation: compare unchecked task docs with matching artifacts, history, recent commits, and alignment pages before recommending next work. | `ship-end`, `codebase-status`, `exec`, task docs convention. | Fixture repo with stale unchecked task and existing artifact; expected route is tracker reconciliation, not repeated work. |
| 4 | Skill visibility and slash/dollar route confusion | Skill/pack category 4,102 messages; 29 lesson headings; `$pack` and `/pack` 104 combined. | Plugin/integration or skill | skill route healthcheck: resolve command, active runner, pack status, mirror path, version, archive collision, and reload requirement before work starts. | `pack`, `skills`, project config provisioning. | Layer1 tests for missing command fallback, installed-but-stale pack, archive duplicate, and Codex/Claude handoff normalization. |
| 5 | Visual fixes that pass code checks but remain wrong on screen | Frontend/animation category 683 messages; 9 lesson headings; recent repeated drawer/rich-menu regressions. | Skill convention and browser proof harness | visual regression acceptance packet: expected state timeline, known-good comparator, dev-server freshness, screenshot/DOM proof, and no source churn before visible target is confirmed. | `investigate`, frontend app workflow, Browser/Computer Use capability when available. | Focused browser smoke or Playwright screenshot check plus a code-source regression test for state-machine assumptions. |
Recommended next skill: `$targeted-skill-builder development stuck-state preflight and unstick routing`.
Why this first: It addresses the broadest verified workflow gap and should reduce repeated manual prompts across status drift, invisible changes, report-only mistakes, verification loops, and skill route confusion. Owner surface is shared workflow conventions plus `exec`/`investigate`/`ship`/`ship-end`/`session-triage`; validation should include layer1 contract tests and one focused benchmark smoke.
Review Gates
Evidence Coverage
Is the local-history evidence sufficient to treat these as recurring development stuck points?
Assumptions And Confidence
Which caveat should govern use of this report?
Recommended Path
Which remediation path should be treated as the next concrete action?
Proposed File Changes
Are the proposed durable artifacts for this analysis acceptable?
Post-Approval Route
After approval, how should this report route next work?
Compile Feedback And Answers
Use feedback YAML for concerns before answering all gates. Use final answers only when the report is ready for agent review.