YurunChen/repo-docs-skills / docs
repo-docs
FlaggedBuild and maintain a Markdown guide that helps humans understand a repository through real behavior, concepts, and evidence. Use when a user asks to understand a repo, generate or update repo-docs, answer repo-architecture/onboarding questions, seed docs for a new project, sync docs after code changes, or delete generated repo docs.
case-studies/generated/aider/repo-docs/modules/edit-lifecycle.md
View on GitHub# Edit Lifecycle
## Why edits are gated before writes
An assistant reply is only a proposal. Before any file changes, the tool asks a short sequence of questions: does the proposal make sense, is the target allowed, would it overwrite user work, and what feedback should return if something fails?
The lifecycle gates are:
| Gate | Question answered |
| --- | --- |
| Parse | Did the model reply use an edit format this coder understands? |
| Dry run | Can the proposed edit be applied as structured edits before touching files? |
| Permission | Is each target file already approved for this session? |
| Dirty-work checkpoint | Does a target file need a pre-edit commit so user work remains undoable? |
| Write | Can the concrete coder apply the edit to disk? |
| Reflect | If parsing or matching failed, what feedback should the model see next? |
| Verify | Should lint, shell output, or tests feed back into the conversation? |
This is the concept behind the walkthrough’s hard part: the system is designed for model output that may be wrong, incomplete, or pointed at the wrong file.
## How proposals become checked file changes
The shared lifecycle lives in `Coder.apply_updates()`. It asks the concrete coder for edits, runs a dry-run application, filters edits through the preparation step, then asks the concrete coder to apply the edits for real. For diff-style edits, `EditBlockCoder` parses and applies SEARCH/REPLACE blocks.
The concrete diff coder has two notable behaviors. First, a replacement must match real file content, with a fallback that can search other in-chat files when the named file does not match. Second, failure raises a detailed edit-format error that includes the failed block and sometimes nearby matching lines. The shared lifecycle catches that error and stores it as reflected feedback.
The file authority rules live in the allowed-to-edit step: in-chat files are allowed, gitignored files are skipped, missing files require create confirmation, and existing files outside the chat require confirmation before they are added to the editable set.
The git protection rules live in the dirty-check, preparation, and dirty-commit steps. A dirty target file can be committed before Aider writes the model edit. Later, the auto-commit step commits the Aider edit itself when repo and options allow it.
## How to verify the lifecycle
Use these focused tests to verify the concept:
```bash
python -m pytest tests/basic/test_editblock.py::TestUtils::test_full_edit tests/basic/test_editblock.py::TestUtils::test_full_edit_dry_run
python -m pytest tests/basic/test_coder.py::TestCoder::test_gpt_edit_to_dirty_file tests/basic/test_coder.py::TestCoder::test_only_commit_gpt_edited_file
```
The tests prove successful edit application, dry-run no-write behavior, dirty-file pre-commit, and edited-file-only commit scope.
## Where to read next
For the end-to-end flow, read [the walkthrough of one terminal request becoming an edit](../walkthroughs/one-real-run.md). For exact claim support, audit [the source evidence ledger](../references/source-evidence.md).
Evidence status: Confirmed unless noted.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |