docs: disco como ram planning-with-files#36
Merged
Conversation
Article analyzing the persistent-planning-files pattern via OthmanAdi/planning-with-files v3.4.0, grounded in the Manus July-2025 context-engineering paper and Anthropic's docs on context rot. * Symptom diagnosis: 4 concrete degradation patterns * Theory: 2 of 6 Manus principles (filesystem as memory + todo recitation) * Implementation: v3.4.0 actual mechanics (3 files + PreToolUse hook) * Verifiable benchmark from docs/evals.md (96.7% pass rate, 3/3 A/B, +68% tokens, +17% time) * Failure modes including the v3.4 PLANNING_DISABLED=1 opt-out * When to use / not use, plus 15-min quickstart ~2890 words
Apply review feedback from two parallel subagents (tech-lead profile + counter-evidence researcher). Sourcing fixes - Replace '18 IDEs' (did not match README) with '60+ agents, dozen with native hooks' — exact phrasing from the repo README - Replace vague '24.8K stars' with 24,850 GitHub stars + 2,111 forks (verified via gh api) - Replace temporal trap 'when Meta hadn't yet acquired them' with precise 'months before Meta acquired them in December 2025' - Tighten the eval-claim phrasing from asserted counts to what's actually in docs/evals.md New section: 'Lo que planning-with-files aún no resuelve' - Vercel benchmark (Jan 2026): AGENTS.md inline 100% vs skill default 53% (no improvement vs baseline). 56% of eval cases: skill never invoked. This contradicts the core 'filesystem as memory' thesis. - Three self-reported issues as auto-evidence of limits: #178 (auto-continue unrequested work), #146 (cross-session leak), #19 (140K-token carry-over failure, 24 comments open) - Anthropic divergence: their 'long-running agents' harness uses claude-progress.txt + JSON feature tracker + two-agent harness, not the three-markdown-files pattern; the original theory source is moving away from its own recommendation Quickstart tightened - Add 'cd' to project directory before install - Add 'flag --skill planning-with-files' to the npx command (verified in docs/installation.md) - Add warnings table: missing --skill flag, Windows + Git Bash - Add note that /plugin install path unlocks /plan-goal and /plan-loop commands not available via npx skills add - Tell user to expect task_plan.md, findings.md, progress.md in project root Terms defined inline for non-experts - Add KV-cache and mask-don't-remove glossary at first use in section 2 - Remove non-canonical 'tool thrash' from the list of Manus principles (it's a corollaire, not a separate principle) Numbering - Sections renumbered 5->6, 6->7, 7->8, 8->9, 9->10 to accommodate new section - Sub-sections 5.1-5.3 renamed to 6.1-6.3 to match new parent References - Replace orphan [^rot-anthropic] (no URL) with [^vercel] and [^anthropic-harness], both cited in body - All 6 footnote URLs verified 200 OK or transparently flagged as unfindable ~3926 words (was 2890).
TellMeAlex
approved these changes
Jul 6, 2026
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.
📋 Artículo — 2.890 palabras
Resumen
Análisis del patrón 'planes persistentes en disco' para coding agents, usando OthmanAdi/planning-with-files v3.4.0 como implementación canónica. Conecta el patrón con los 6 principios de context engineering que el equipo de Manus publicó el 18 de julio de 2025, valida con cifras del propio benchmark del repo (96.7% pass rate, 3/3 A/B wins, +68% tokens, +17% tiempo) y separa cuándo funciona de cuándo es overhead disfrazado.
Estructura
Tipo
tipo: ensayo— análisis fundamentado con opinión técnica.Referencias verificadas
Tests reales ejecutados
tipo: ensayo, no investigacion)