Menu
Use when creating or updating current-state project context documentation under docs/context/.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when a user needs architecture or product-design sparring on system design, runtime boundaries, config, deployment, operations, or implementation plans; ask one focused question at a time.
Use when ready to ship confirmed local changes through a draft PR: check dirty-worktree scope, create a branch, stage only intended paths, commit, push, open a PR, wait for CI, and fix red checks.
Use when reviewing local code changes before a PR: review my changes/code, check my work, security review, review before push; rank bugs, security, perf, and production risks.
Triage CodeRabbitAI review comments on current PR, fix legitimate issues, push, resolve threads
Create a committed Markdown todo in ~/.create-todo from a todo, task, follow-up, $create-todo request, or current conversation context.
Use when creating concise Markdown docs-as-code for critical user journeys, flows, acceptance scenarios, service blueprints, telemetry, portfolios, story maps, and coverage matrices.
| name | yarstack-repo-context-docs |
| description | Use when creating or updating current-state project context documentation under docs/context/. |
| disable-model-invocation | true |
Update docs/context/ in the project root so it accurately reflects the current codebase state after the latest changes. This is current-state documentation, not a history log.
docs/context/ inside the project rootBefore deciding how to update docs/context/, determine whether this repository is a single-project repo or a monorepo / multi-unit repo.
Use repository inspection commands such as:
git ls-filesfind . -maxdepth 3 -type d | sortfind . -maxdepth 3 -type f | sorttree -L 3 -I 'node_modules|dist|build|coverage|.git|vendor|tmp|.turbo|.next|target|bin|out' if tree is availableLook for signals such as:
pnpm-workspace.yamlpackage.json with workspacesturbo.jsonnx.jsonlerna.jsongo.mod filescmd/deployment/, infra/, k8s/, helm/, charts/, docker-compose*.yml, Jenkinsfile, .github/workflows/Classify the repo as:
Do not infer architectural category from directory name alone.
Services and apps may live in any directory such as apps/, services/, cmd/, backend/, products/, src/, or elsewhere.
Determine whether something is an app, service, package, tool, or platform area from evidence such as:
Context docs must reflect architecture and behavior, not merely folder layout.
A domain is a stable business or technical concern, not just a top-level directory.
In a monorepo, context must document both:
Do not mirror the source tree mechanically inside docs/context/.
Context docs are consumed at different bandwidth levels. Write each file for its tier:
summary.md, context-map.md)Read on every session start. Must be scannable in seconds. Keep each under 80 lines. Together these two files give a developer enough orientation to know where to look next.
summary.md provides the "what and how" of the project. context-map.md is a pure index — pointers only, no content.
Loaded when working in a specific area. Can be longer (up to 250 lines) and more detailed. Each file should be self-contained for its topic.
The codebase itself. Never documented exhaustively in context docs. If a fact can be found with a targeted grep or read of source code, it belongs here, not in docs/context/.
docs/context/ If MissingIf docs/context/ does not exist, create it.
summary.md — sections: What, Architecture, Core Flow, System State, Capabilities, Tech Stackterminology.md — stable term definitions in term — definition formatpractices.md — proven conventions and invariantscontext-map.md — pure index of all context files; one entry per line (~150 chars max), grouped by section, relative links only; cap at 60 linescontext-map.md formatEach entry follows the pattern: - [short-label](relative/path.md) — phrase where the phrase is under 10 words. Group entries under headings that match the docs/context/ folder structure. Never put topic content, summaries, or explanations into context-map.md.
Use a compact structure such as:
summary.mdterminology.mdpractices.mdcontext-map.mddocs/context/<domain>/*.mdUse this baseline structure when applicable:
summary.mdterminology.mdpractices.mdcontext-map.mdmonorepo/ — repo topology, boundaries, build/dev modelapps/ — user-facing deployable applicationsservices/ — backend services, workers, jobs, daemons, APIspackages/ — shared reusable modules with meaningful contractsplatform/ — deployment/runtime/infrastructure behaviordomains/ — cross-cutting business or technical concernsflows/ — end-to-end system and user-facing flowsOnly create folders that are justified by repository reality.
If context content conflicts with codebase reality, code and active configuration are truth.
Priority order when resolving conflicts:
Update context to match actual current behavior.
Context docs are working hypotheses about the codebase, not authoritative specs. When acting on a claim from a context file, verify it against source code before relying on it. If the code disagrees, the code is right and the context doc needs correction.
docs/context/**Write durable, present-tense, current-state documentation only.
summary.md, context-map.md) stay under 80 lines. Tier 2 files stay under 250 lines; split when neededdocs/context/When creating or updating context docs, always follow this order:
context-map.md to reflect the changeNever write topic content into context-map.md. The index points to knowledge; it does not contain knowledge.
If a topic file is deleted, remove its entry from context-map.md in the same pass.
Record only facts supported by code, config, or tests.
Document patterns only if they are both:
Document rejected anti-patterns only if this task revealed a durable architectural rule that is clearly reflected in current code or enforced structure.
The rationale must be written as a current rule, not as a historical story.
The following can always be obtained by reading or grepping the codebase. Storing them creates staleness risk with zero information gain:
practices.md if non-obvious, not the names themselves)Rule: if grep or git log can answer it in under 10 seconds, it does not belong in context docs.
If git status --porcelain shows no uncommitted changes, do a full scan.
Read all existing docs/context/ files first to understand current documented claims.
Do NOT use background agents or Explore agents for discovery. Read files directly using Read, Glob, and Grep tools. This avoids producing huge intermediate output that wastes context.
Inspect relevant files directly such as:
Keep reads focused — read only what you need to understand architecture and behavior. Do not dump entire large files.
Identify:
Find:
docs/context/Fix or create docs according to repository shape.
Update:
summary.mdterminology.mdpractices.mdcontext-map.mdUpdate or create:
monorepo/* for topology, dependency direction, build/dev model, boundariesapps/* for user-facing deployable appsservices/* for backend services/workers/jobs/APIspackages/* for meaningful shared modules and contractsplatform/* for runtime and deployment behaviordomains/* for cross-cutting concernsflows/* for end-to-end behavior crossing unitssummary.mdUpdate only if monorepo-wide or project-wide truth has materially changed.
context-map.mdEnsure it indexes the current file set. Maintain one-line-per-entry format; do not add summaries or topic content.
Read edited files and confirm they reflect current state and contain no prohibited content.
If git status --porcelain shows uncommitted changes, do a change-focused update.
Determine whether the repo is single-project or monorepo / multi-unit before mapping changes.
Use git diff --name-only and, if useful, git status --porcelain.
Cluster changed files into one or more of these:
Use these rules:
docs/context/apps/...docs/context/services/...docs/context/packages/...docs/context/monorepo/...docs/context/platform/...docs/context/domains/...docs/context/flows/...For single-project repos, use simpler domain/flow/platform placement as appropriate.
For each affected topic:
terminology.md for stable active termspractices.md for durable enforced conventions or invariantssummary.md only if high-level What / Architecture / Core Flow / System State / Capabilities / Tech Stack materially changedcontext-map.md to reflect the current file set; maintain one-line-per-entry formatRead back all edited files and confirm they contain only present-tense current-state documentation.
Run when context docs need cleanup after many incremental updates, or when explicitly requested.
context-map.mdcontext-map.md entries that are missing, orphaned, or overly verboseCombine files that cover the same topic into one file. Prefer the file with the more accurate name.
If the same fact appears in multiple files, keep it in the most specific file and remove from others.
For each non-obvious claim, grep or read source to confirm. Remove or correct claims that no longer hold.
Remove:
Rebuild context-map.md from the surviving file set. Maintain one-line-per-entry format.
Read all modified files. Confirm no prohibited content, no stale claims, correct tier sizing.
When the repo is monorepo / multi-unit:
monorepo/Use for repository-wide structure such as:
apps/Use for user-facing deployable applications.
Each app file or folder should explain things such as:
services/Use for backend services, APIs, workers, jobs, daemons, queues, importers, schedulers, and other deployable runtime processes.
Document:
packages/Use for shared libraries/modules with meaningful contracts or architectural significance.
Document:
Do not create package docs for trivial helpers unless they carry meaningful architecture or contracts.
platform/Use for:
domains/Use for cross-cutting concerns such as:
A domain may span multiple apps, services, packages, and platform areas.
Do not define domains purely from folder names.
flows/Use for end-to-end behavior that crosses boundaries, such as:
After updating, verify:
summary.md, context-map.md) are under 80 lines; Tier 2 files are under 250 linesdocs/context/context-map.md indexes everything using relative links with one-line-per-entry format, under 60 linessummary.md contains required sections and matches realityMake the necessary updates to docs/context/ and stop.
Do not print a long narrative report.
If a brief result summary is needed, keep it short and factual, for example:
docs/context/Do not include dates, progress language, or historical narrative in the documentation itself.