{
  "markdown": "# ASP — Anticipating Shadow Points\n\n[![Version](https://img.shields.io/github/v/release/ulissesflores/anticipating-shadow-points?sort=semver&color=blue)](https://github.com/ulissesflores/anticipating-shadow-points/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Claude Code 2.1.139+](https://img.shields.io/badge/Claude%20Code-2.1.139%2B-blue.svg)](https://code.claude.com)\n[![Docs](https://img.shields.io/badge/docs-online-blue.svg)](https://ulissesflores.github.io/anticipating-shadow-points/)\n[![Citation](https://img.shields.io/badge/cite-CITATION.cff-purple.svg)](CITATION.cff)\n[![Code of Conduct](https://img.shields.io/badge/contributor%20covenant-2.1-green.svg)](CODE_OF_CONDUCT.md)\n[![Plugin Marketplace](https://img.shields.io/badge/plugin-marketplace--ready-brightgreen.svg)](#install)\n\n## Ship ambitious work without missing the obvious.\n\nASP is a Claude Code skill that lifts shadow-point coverage from **47% to 100%** on non-trivial tasks — through forced pre-mortem, independent validator, and `claude -p /goal` subprocess execution.\n\n🇬🇧 English (this file) · [🇪🇸 Español](docs/README.es.md) · [🇧🇷 Português](docs/README.pt.md) · [🇮🇹 Italiano](docs/README.it.md) · [🇮🇱 עברית](docs/README.he.md)\n\n---\n\n## The proof\n\n<table>\n<tr>\n<td align=\"center\" width=\"33%\">\n<h1>47% → 100%</h1>\nshadow-point coverage<br>(baseline vs. with ASP)\n</td>\n<td align=\"center\" width=\"33%\">\n<h1>12</h1>\nnon-negotiable Iron Laws<br>enforced at runtime\n</td>\n<td align=\"center\" width=\"33%\">\n<h1>5</h1>\nstructured evals<br>across real domains\n</td>\n</tr>\n</table>\n\n### Same task, two outcomes\n\nReal subagent dispatches from the 2026-05-17 RED/GREEN baseline. Task: *\"Add a NOT NULL column `tier` (default 'free') to `user_profiles`. Table has 1M rows in production.\"*\n\n<table>\n<tr>\n<td width=\"50%\" valign=\"top\">\n\n**❌ Without ASP — baseline agent**\n\n```sql\nALTER TABLE user_profiles\n  ADD COLUMN tier text\n  NOT NULL DEFAULT 'free';\n\nCREATE INDEX CONCURRENTLY\n  idx_user_profiles_tier\n  ON user_profiles (tier);\n```\n\n*~60% coverage.* Misses: replica lag, app deploy ordering, monitoring spike, trigger interaction, foreign key cascade.\n\n</td>\n<td width=\"50%\" valign=\"top\">\n\n**✅ With ASP — same agent, same task**\n\n```text\nPre-mortem (30 days out):\n 1. Full table rewrite locks\n 2. RLS policy not updated\n 3. Stale TS client types\n 4. Service-role bypass risk\n 5. Replica lag during DDL\n 6. App deploy ordering\n 7. Monitoring spike\n 8. Backup window collision\n 9. Index INVALID state\n10. WAL/disk pressure\n11. CDC realtime flood\n12. Rollback impossible\n13. CPU credit exhaustion\n14. Audit trail missing\n15. Time-zone in cron logic\n```\n\n*100% coverage.* Each surfaces a mitigation before any SQL runs.\n\n</td>\n</tr>\n</table>\n\n*Built on proven methodology · [Klein pre-mortem](https://hbr.org/2007/09/performing-a-project-premortem) · [Berkeley MAST 14-mode](https://arxiv.org/abs/2503.13657) · [Plan-and-Act](https://arxiv.org/abs/2503.09572) · Reflexion · empirically validated 2026-05-17*\n\n---\n\n## What ASP does\n\n<table>\n<tr>\n<td width=\"50%\" valign=\"top\">\n\n### 🎯 Pre-mortem before code\n\n\"Imagine the failure. Now describe why.\" Prospective hindsight — Mitchell, Russo & Pennington (1989) showed it generates ~30% more reasons than imagining the same event as merely possible; Klein (2007, HBR) operationalized it as the pre-mortem. ASP runs it on every non-trivial task.\n\n</td>\n<td width=\"50%\" valign=\"top\">\n\n### 🔍 MAST 14-mode checklist\n\nBerkeley's failure taxonomy forces coverage of less-obvious categories — time/timezone, observability, op-ex, contract drift — that free-form pre-mortem clusters away from.\n\n</td>\n</tr>\n<tr>\n<td width=\"50%\" valign=\"top\">\n\n### 🛡️ Independent validator\n\nA fresh-prompt subagent audits the plan before execution. Self-critique fails on high-confidence hallucinations; prompt isolation breaks that collusion. **Iron Law 2**.\n\n</td>\n<td width=\"50%\" valign=\"top\">\n\n### ⚡ `claude -p /goal` kernel\n\nSpawns Anthropic's official worker/evaluator kernel as a subprocess. Empirically validated 2026-05-17. **Iron Law 11**: never trust `$?` — parse JSON.\n\n</td>\n</tr>\n</table>\n\n---\n\n## See it run\n\n```text\n$ /asp Add a NOT NULL column `tier` to user_profiles. 1M rows.\n\nPhase 1 — Parallel research (codebase + web + recall.py)          ✓\nPhase 2 — Shadow-point detection (Klein + MAST 14-mode)            ✓ 14 found\nPhase 4 — Macro plan + Deliverables Register (D01..D08)            ✓\nPhase 5 — Independent validator (separate-prompt subagent)         APPROVE\nPhase 7 — Awaiting user approval of charter + plan + deliverables  ✓\nPhase 8 — Micro-TODO contract emitted: 23 tasks (PRE/ACT/POST/ACC/FAL)\nPhase 9 — claude -p /goal autonomous execution                     → running\n\nGoal Spec: All 23 tasks completed with ACCEPTANCE-TEST evidence;\n           all 8 deliverables marked `aceito`; 12 Iron Laws respected.\nHard stops: turn > 80 · elapsed > 30min · 3 consecutive falsifications.\n```\n\nEvery step is auditable. Every task has a verifiable acceptance test. Nothing ships without fresh evidence.\n\n---\n\n## Install\n\n### Path A — Plugin marketplace (recommended, Claude Code 2.1+)\n\n```bash\nclaude plugin marketplace add ulissesflores/anticipating-shadow-points\nclaude plugin install anticipating-shadow-points@anticipating-shadow-points\n```\n\nInvoke: `/anticipating-shadow-points:asp <task>` in any Claude Code session.\n\n<details>\n<summary><b>Other install paths</b> — dev mode and standalone script</summary>\n\n### Path B — Local plugin dev mode (`--plugin-dir`)\n\nFor testing/development without installing permanently:\n\n```bash\ngit clone https://github.com/ulissesflores/anticipating-shadow-points.git ~/Developer/ASP\nclaude --plugin-dir ~/Developer/ASP\n```\n\nLoaded only for that session. Invoke: `/anticipating-shadow-points:asp <task>`.\n\n### Path C — Standalone `install.sh` (legacy, full control)\n\nFor users who want bare `/asp` invocation (no plugin namespace) or want to inspect/modify before install:\n\n```bash\ngit clone https://github.com/ulissesflores/anticipating-shadow-points.git ~/Developer/ASP\ncd ~/Developer/ASP\n./scripts/verify.sh --pre-install\n./scripts/install.sh\n```\n\nInvoke: `/asp <task>` (no namespace). Uninstall: `./scripts/uninstall.sh`.\n\n</details>\n\n**Requirements**: Claude Code 2.1.139+ · `bash` · `jq` · *(optional)* `~/.agent/` agentic-stack for `recall.py` lessons retrieval (silently skipped if absent).\n\n---\n\n## When to reach for ASP\n\n<table>\n<tr>\n<th align=\"left\" width=\"50%\">✅ Use ASP for</th>\n<th align=\"left\" width=\"50%\">❌ Skip ASP for</th>\n</tr>\n<tr>\n<td valign=\"top\">\n\n- Features touching data or shared state\n- Migrations (schema, dependency, API)\n- Refactors across many files\n- Deploys with external dependencies\n- Architecture decisions\n- Root-cause debug investigations\n\n</td>\n<td valign=\"top\">\n\n- Typo fixes\n- Single-line edits\n- Read-only questions (\"what does X do?\")\n- Tasks you can finish in under 5 minutes\n\n</td>\n</tr>\n</table>\n\n---\n\n## Troubleshooting\n\n<details>\n<summary><b><code>claude plugin install</code> fails with SSH permission denied</b></summary>\n\nIf you see `git@github.com: Permission denied (publickey)` during `claude plugin install`, your git is configured to use SSH but you don't have an SSH key registered with GitHub. The `marketplace add` step has automatic HTTPS fallback, but `install` does not (as of Claude Code 2.1.143).\n\nOne-time workaround:\n\n```bash\ngit config --global url.\"https://github.com/\".insteadOf \"git@github.com:\"\n```\n\nThen retry `claude plugin install`.\n\n</details>\n\n<details>\n<summary><b><code>/asp</code> works but <code>/anticipating-shadow-points:asp</code> doesn't (or vice versa)</b></summary>\n\nThe two invocations come from different install paths and don't conflict:\n\n- `/asp` works after Path C (`install.sh`) — installs without plugin namespace.\n- `/anticipating-shadow-points:asp` works after Path A or Path B — plugin-namespaced.\n\nBoth can coexist.\n\n</details>\n\n<details>\n<summary><b>Plugin name shows up twice (<code>name@marketplace</code>)</b></summary>\n\n`anticipating-shadow-points@anticipating-shadow-points` is correct — it's `<plugin-name>@<marketplace-name>`, both happen to be the same string because the repo self-hosts its marketplace. The doubled-up appearance is visual only.\n\n</details>\n\n---\n\n## Whitepapers\n\nBoth whitepapers are published under **Codex Hash Research Laboratory Whitepaper Series · 2026** with permanent Zenodo concept DOI [10.5281/zenodo.20276631](https://doi.org/10.5281/zenodo.20276631) — always resolves to the latest version.\n\n| # | Title | PDF | Markdown source |\n|---|---|---|---|\n| 1 | *ASP: An Operational Pre-Mortem Skill for LLM Coding Agents — An Experience Report* | [`paper/asp-preprint.pdf`](paper/asp-preprint.pdf) | [`paper/asp-preprint.md`](paper/asp-preprint.md) |\n| 2 | *Graceful Refusals as Silent Successes: A Pre-Registered Protocol for Characterising `claude -p` Exit-Code Semantics* | [`paper/iron-law-11.pdf`](paper/iron-law-11.pdf) | [`paper/iron-law-11.md`](paper/iron-law-11.md) |\n\nThe Markdown sources are canonical; the PDFs are the published artefacts. Both are also attached to the [GitHub Release v1.0.0](https://github.com/ulissesflores/anticipating-shadow-points/releases/tag/v1.0.0) and archived under the Zenodo DOI for permanent citation. To rebuild the PDFs from source, see [CONTRIBUTING.md § Rebuilding the whitepaper PDFs](CONTRIBUTING.md#rebuilding-the-whitepaper-pdfs).\n\n---\n\n## Deeper reading\n\n- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)** — 10-part SOTA design document: academic background, v1→v5 architectural journey, empirical discoveries (including Iron Law 11 finding), derivation of all 12 Iron Laws, open questions.\n- **[5 structured evals](skills/anticipating-shadow-points/evals/)** — domain-specific shadow-point tests covering Supabase migration, edge function deploy, util refactor, RLS policy change, cron skill conflict.\n- **[12 Iron Laws](skills/anticipating-shadow-points/SKILL.md)** — non-negotiable runtime discipline.\n\n---\n\n## Community\n\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** — how to contribute (code, docs, evals, translations).\n- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** — Contributor Covenant 2.1.\n- **[SECURITY.md](SECURITY.md)** — vulnerability disclosure policy.\n- **[CHANGELOG.md](CHANGELOG.md)** — release history.\n- **[AGENTS.md](AGENTS.md)** — rules for AI agents editing this repository.\n\nNative-speaker review of ES/IT/HE translations welcomed via PR.\n\n---\n\n## Author\n\n**[Carlos Ulisses Flores](https://ulissesflores.com)** — CTO & Chief Researcher at Codex Hash Research Laboratory · MSc AI candidate, American Global Tech University · São Paulo, Brazil · [ORCID `0000-0002-6034-7765`](https://orcid.org/0000-0002-6034-7765) · [Lattes `6905246706890561`](http://lattes.cnpq.br/6905246706890561) · [@ulissesflores on GitHub](https://github.com/ulissesflores)\n\nDomain focus: Quantitative Finance & Web3 · Hardware & IoT · AI & Data Science. The multilingual docs reflect the maintainer's working languages — Portuguese (native), English/Spanish (fluent), Italian (conversational), Hebrew (academic reading).\n\nResearch synthesis, initial drafting, and verification scripts produced in collaboration with Claude (Anthropic, Opus 4.7) under explicit human-in-the-loop direction. See [AUTHORS](AUTHORS) and [ARCHITECTURE.md](docs/ARCHITECTURE.md) Parts 5–6 for the contribution model.\n\n---\n\n## Cite this work\n\nIf you use ASP in published work, an evaluation, or a production deployment, please cite via [CITATION.cff](CITATION.cff) — GitHub's \"Cite this repository\" button uses this file automatically. The four methodological references (Klein, MAST, Plan-and-Act, Reflexion) are listed there and should be cited alongside ASP when discussing the methodology.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE). Acknowledgements: ASP integrates patterns from [obra/superpowers](https://github.com/obra/superpowers) and aligns with the [agentskills.io](https://agentskills.io) open standard.\n",
  "bytes": 11970,
  "sha": "be552ec93187ccdecd5288c9ea0cea219031935f6b7784080f37ea5bb75319e1",
  "repo_slug": "ulissesflores/anticipating-shadow-points",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_ulissesflores_anticipating_shadow_points_71d75b27/readme"
}