documenting-decisions — Skillopedia

Documenting Decisions Checkpoint tags | Tag | When to mark | | ------- | ----------------------------------------------------------------------------------------------------- | | | New abstractions, deps, data models, component boundaries — anything that shapes long-term structure. | | | You resolved an ambiguity in the task by choosing an interpretation. | | | Changed a public API, config schema, CLI flag, env var, or wire format. | | | Touched auth, crypto, permissions, network exposure, or input validation. | | | Created a migration, data deletion, deployment trigger, or external side effe…

\\n'\n ADDED_DEPS+=$(diff \u003c(git show origin/main:package.json 2>/dev/null | jq -r '.devDependencies // {} | keys[]' 2>/dev/null | sort) \\\n \u003c(jq -r '.devDependencies // {} | keys[]' package.json 2>/dev/null | sort) \\\n | grep \"^>\" | sed 's/^> /npm-dev: /')\nfi\n\n# Python\nif git diff origin/main --name-only | grep -qE \"(requirements.*\\.txt|pyproject\\.toml|setup\\.cfg)\"; then\n # For requirements.txt\n for f in $(git diff origin/main --name-only | grep \"requirements.*\\.txt\"); do\n ADDED_DEPS+=$(diff \u003c(git show origin/main:\"$f\" 2>/dev/null | grep -v \"^#\" | cut -d= -f1 | cut -d'>' -f1 | cut -d'\u003c' -f1 | tr -d ' ' | sort) \\\n \u003c(grep -v \"^#\" \"$f\" | cut -d= -f1 | cut -d'>' -f1 | cut -d'\u003c' -f1 | tr -d ' ' | sort) \\\n | grep \"^>\" | sed 's/^> /pip: /')\n done\nfi\n\nif [ -n \"$(echo \"$ADDED_DEPS\" | tr -d '[:space:]')\" ]; then\n echo \"🏗️ ARCH: New dependencies detected\"\n echo \"$ADDED_DEPS\" | grep -v \"^$\"\nfi\n```\n\n## 2. Public API surface diff (IFACE)\n\nDetect changes to exported functions, route definitions, config schemas.\n\n```bash\n#!/bin/bash\n# canary-iface.sh — detect interface changes\nFLAGS=\"\"\n\n# OpenAPI / Swagger changes\nif git diff origin/main --name-only | grep -qiE \"(openapi|swagger)\\.(json|ya?ml)\"; then\n FLAGS+=\"OpenAPI schema modified\\n\"\nfi\n\n# GraphQL schema changes\nif git diff origin/main --name-only | grep -qiE \"\\.graphql$|schema\\.gql\"; then\n FLAGS+=\"GraphQL schema modified\\n\"\nfi\n\n# Route file changes (common patterns)\nif git diff origin/main -- '*.ts' '*.js' '*.py' | grep -qE \"^[+].*(router\\.(get|post|put|delete|patch)|@app\\.(route|get|post)|FastAPI|express\\.Router)\"; then\n FLAGS+=\"HTTP route definitions changed\\n\"\nfi\n\n# Environment variable additions\nif git diff origin/main -- '*.ts' '*.js' '*.py' '*.go' '*.rs' | grep -qE \"^[+].*process\\.env\\.|^[+].*os\\.environ|^[+].*env::var\"; then\n NEW_ENVS=$(git diff origin/main -- '*.ts' '*.js' '*.py' '*.go' '*.rs' \\\n | grep -E \"^[+].*process\\.env\\.|^[+].*os\\.environ|^[+].*env::var\" \\\n | grep -oE \"(process\\.env\\.\\w+|os\\.environ\\[.[^\\]]+\\]|env::var\$.[^)]+\$)\" | sort -u)\n FLAGS+=\"New environment variables: $NEW_ENVS\\n\"\nfi\n\n# CLI argument changes\nif git diff origin/main -- '*.py' | grep -qE \"^[+].*(add_argument|add_option|click\\.(option|argument))\"; then\n FLAGS+=\"CLI arguments modified\\n\"\nfi\n\nif [ -n \"$FLAGS\" ]; then\n echo \"🔌 IFACE: Public interface changes detected\"\n echo -e \"$FLAGS\"\nfi\n```\n\n## 3. Migration and irreversible operation detection (IRREV)\n\n```bash\n#!/bin/bash\n# canary-irrev.sh — detect irreversible operations\nFLAGS=\"\"\n\n# Migration files\nMIGRATIONS=$(git diff origin/main --name-only | grep -iE \"(migrations?/|alembic/|flyway/|liquibase)\" || true)\nif [ -n \"$MIGRATIONS\" ]; then\n FLAGS+=\"Migration files:\\n$MIGRATIONS\\n\"\nfi\n\n# Destructive SQL\nif git diff origin/main -- '*.sql' '*.py' '*.ts' '*.js' | grep -qiE \"^[+].*(DROP|TRUNCATE|DELETE FROM|ALTER.*DROP)\"; then\n FLAGS+=\"Destructive SQL detected\\n\"\nfi\n\n# File deletion operations\nif git diff origin/main -- '*.py' '*.ts' '*.js' '*.go' '*.rs' | grep -qE \"^[+].*(os\\.remove|os\\.unlink|shutil\\.rmtree|fs\\.unlink|fs\\.rm|remove_dir_all)\"; then\n FLAGS+=\"File deletion operations in code\\n\"\nfi\n\n# Deployment config changes\nif git diff origin/main --name-only | grep -qiE \"(deploy|\\.github/workflows|Dockerfile|docker-compose|k8s/|helm/|terraform/)\"; then\n DEPLOY_FILES=$(git diff origin/main --name-only | grep -iE \"(deploy|\\.github/workflows|Dockerfile|docker-compose|k8s/|helm/|terraform/)\")\n FLAGS+=\"Deployment config changes:\\n$DEPLOY_FILES\\n\"\nfi\n\nif [ -n \"$FLAGS\" ]; then\n echo \"⚠️ IRREV: Irreversible operations detected\"\n echo -e \"$FLAGS\"\nfi\n```\n\n## 4. Security-sensitive path detection (SEC)\n\n```bash\n#!/bin/bash\n# canary-sec.sh — detect security-sensitive changes\nFLAGS=\"\"\n\n# Auth-related file changes\nAUTH_FILES=$(git diff origin/main --name-only | grep -iE \"(auth|login|session|token|credential|secret|password|permission|rbac|acl|oauth|jwt|crypto)\" || true)\nif [ -n \"$AUTH_FILES\" ]; then\n FLAGS+=\"Auth-related files modified:\\n$AUTH_FILES\\n\"\nfi\n\n# New network listeners\nif git diff origin/main -- '*.py' '*.ts' '*.js' '*.go' '*.rs' | grep -qE \"^[+].*(\\.listen\\(|bind\\(|serve\\(|createServer|http\\.Server|net\\.Listen)\"; then\n FLAGS+=\"New network listener\\n\"\nfi\n\n# CORS/CSP changes\nif git diff origin/main | grep -qiE \"^[+].*(cors|content-security-policy|access-control-allow)\"; then\n FLAGS+=\"CORS/CSP headers modified\\n\"\nfi\n\n# Raw SQL construction (injection risk)\nif git diff origin/main -- '*.py' '*.ts' '*.js' | grep -qE \"^[+].*(f\\\".*SELECT|f\\\".*INSERT|f\\\".*UPDATE|f\\\".*DELETE|\\`.*\\$\\{.*SELECT)\"; then\n FLAGS+=\"Potential SQL injection: string-interpolated queries\\n\"\nfi\n\n# Hardcoded secrets (crude but useful)\nif git diff origin/main | grep -qE \"^[+].*(password|secret|api_key|apikey|token)\\s*=\\s*['\\\"][^'\\\"]{8,}\"; then\n FLAGS+=\"Potential hardcoded secret\\n\"\nfi\n\nif [ -n \"$FLAGS\" ]; then\n echo \"🔒 SEC: Security-sensitive changes detected\"\n echo -e \"$FLAGS\"\nfi\n```\n\n## 5. Novel file detection (NOVEL)\n\nDetects files added to directories where they have no structural siblings — a sign the agent is inventing a new pattern rather than following an existing one.\n\n```bash\n#!/bin/bash\n# canary-novel.sh — detect novel patterns\nFLAGS=\"\"\n\n# New files in directories with no similar files\nfor NEW_FILE in $(git diff origin/main --name-only --diff-filter=A); do\n DIR=$(dirname \"$NEW_FILE\")\n EXT=\"${NEW_FILE##*.}\"\n\n # Count existing files with same extension in that directory (on main)\n SIBLING_COUNT=$(git ls-tree origin/main \"$DIR/\" 2>/dev/null | grep -c \"\\.$EXT$\" || echo \"0\")\n\n if [ \"$SIBLING_COUNT\" -eq 0 ]; then\n FLAGS+=\"Novel file: $NEW_FILE (no .$EXT siblings in $DIR/)\\n\"\n fi\ndone\n\n# New framework/library imports not used elsewhere in codebase\nfor IMPORT in $(git diff origin/main -- '*.py' | grep -E \"^[+](import |from )\" | sed 's/^+//' | awk '{print $2}' | cut -d. -f1 | sort -u); do\n if ! git grep -q \"import $IMPORT\\|from $IMPORT\" origin/main -- '*.py' 2>/dev/null; then\n FLAGS+=\"Novel import: $IMPORT (not used elsewhere in codebase)\\n\"\n fi\ndone\n\nif [ -n \"$FLAGS\" ]; then\n echo \"🆕 NOVEL: New patterns detected (no existing precedent)\"\n echo -e \"$FLAGS\"\nfi\n```\n\n## 6. Decision marker summary (all categories)\n\nCollects all `DECISION:` markers from changed files and presents them as the PR review summary.\n\n```bash\n#!/bin/bash\n# canary-decisions.sh — collect DECISION: markers from changed files\nMARKERS=$(git diff origin/main --name-only | xargs grep -Hn \"DECISION:\" 2>/dev/null || true)\n\nif [ -n \"$MARKERS\" ]; then\n echo \"📋 DECISION MARKERS found in this PR:\"\n echo \"\"\n echo \"$MARKERS\" | while IFS= read -r line; do\n FILE=$(echo \"$line\" | cut -d: -f1)\n LINE_NUM=$(echo \"$line\" | cut -d: -f2)\n CONTENT=$(echo \"$line\" | cut -d: -f3- | sed 's/^[[:space:]]*//' | sed 's|^//\\s*||;s|^#\\s*||;s|^--\\s*||;s|^\\*\\s*||')\n echo \" $FILE:$LINE_NUM — $CONTENT\"\n done\n echo \"\"\n echo \"Review these decisions before merging.\"\nelse\n echo \"✅ No DECISION: markers — this PR is routine.\"\nfi\n```\n\n## Combining into a single CI step\n\n```bash\n#!/bin/bash\n# canary-all.sh — run all canary checks\necho \"=== Agentic Review Canary Signals ===\"\necho \"\"\n\nbash canary-decisions.sh 2>/dev/null\necho \"\"\nbash canary-deps.sh 2>/dev/null\nbash canary-iface.sh 2>/dev/null\nbash canary-irrev.sh 2>/dev/null\nbash canary-sec.sh 2>/dev/null\nbash canary-novel.sh 2>/dev/null\n\necho \"\"\necho \"=== End Canary Signals ===\"\n```\n\n## GitHub Actions integration\n\n````yaml\nname: Agentic Review Canary\non: pull_request\n\njobs:\n canary:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n with:\n fetch-depth: 0\n - name: Run canary signals\n id: canary\n run: |\n OUTPUT=$(bash .github/scripts/canary-all.sh)\n echo \"$OUTPUT\"\n # Post as PR comment\n if [ -n \"$OUTPUT\" ]; then\n echo \"canary_output\u003c\u003cEOF\" >> $GITHUB_OUTPUT\n echo \"$OUTPUT\" >> $GITHUB_OUTPUT\n echo \"EOF\" >> $GITHUB_OUTPUT\n fi\n - name: Comment on PR\n if: steps.canary.outputs.canary_output\n uses: actions/github-script@v7\n with:\n script: |\n github.rest.issues.createComment({\n owner: context.repo.owner,\n repo: context.repo.repo,\n issue_number: context.issue.number,\n body: '## 🔍 Agentic Review Canary\\n\\n```\\n' +\n '${{ steps.canary.outputs.canary_output }}' +\n '\\n```\\n\\nThese are the sections of this PR that need human review. Everything else is routine.'\n })\n````\n\n## Adapting to your stack\n\nThese scripts are starting points. Tune the file patterns and grep expressions to your project. The important thing is the category mapping — each check should clearly label which of the six categories (ARCH, SCOPE, IFACE, SEC, IRREV, NOVEL) it belongs to, so the reviewer knows why they're looking at something.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":9770,"content_sha256":"c3d5d81d48690dd499448709f5d12e6395cb50c2af240a741965c3f790e35128"},{"filename":"references/decision-markers.md","content":"# Decision markers\n\nWhen making a noteworthy decision during implementation, annotate it inline in the code:\n\n // DECISION:\u003cCATEGORY> — \u003cexplanation>\n\nCategories: ARCH, SCOPE, IFACE, SEC, IRREV, NOVEL\n\nUse these when:\n\n- ARCH: introducing a new abstraction, dependency, data model, or component boundary\n- SCOPE: resolving an ambiguity in the task by choosing an interpretation\n- IFACE: changing a public API, config schema, CLI flag, or env var\n- SEC: modifying auth, crypto, network, permissions, or input validation\n- IRREV: creating a migration, deletion, deployment change, or external side effect\n- NOVEL: writing code with no existing pattern in the repo to follow\n\nDo not mark routine changes. If nothing is noteworthy, no markers are needed.\n\nAfter completing the task, generate DECISION_LOG.md by collecting all DECISION: markers from changed files:\n\n # Decision Log — [task one-liner]\n ## Decisions requiring review\n - **CATEGORY** `file:line` — explanation\n ## Routine changes (skip review)\n [One-line summary]\n\nIf no markers exist, write: \"No noteworthy decisions. All changes follow existing patterns.\"\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":1141,"content_sha256":"ad83e0a76a09d6db3cc92762d2e4c8a03e1bd11136b4fa28f187397f43a1b64e"},{"filename":"references/irreversible-operations.md","content":"# Irreversible operations\n\nNever execute these without explicit human approval:\n\n- Database migrations (create the migration file, do not run it)\n- File or data deletion operations\n- Deployment triggers\n- External API calls with side effects (payments, webhooks, notifications)\n\nFlag all irreversible operations in DECISION_LOG.md under IRREV.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":344,"content_sha256":"f08ae8faab5f9c9b28592b434c6e08b2dc7aef5f412e217d7fa6f64dbe7dfb81"},{"filename":"references/marker-examples.md","content":"# Decision Marker Examples\n\n## Format\n\n```text\n// DECISION:\u003cTAG> — \u003cexplanation>\n```\n\nTag on same line as `DECISION:` prefix. Explanation can wrap to subsequent comment lines. Use language-native comment syntax.\n\n## Examples\n\n```typescript\n// DECISION:ARCH — Using SQLite instead of PostgreSQL. Single-node cache,\n// not shared state. Migrate to Postgres if this goes multi-node.\nconst db = new Database(\"./cache.sqlite\");\n```\n\n```python\n# DECISION:SEC — No rate limiting. Internal-only behind Tailscale.\n# Add rate limiting before any public exposure.\[email protected](\"/internal/sync\", methods=[\"POST\"])\n```\n\n```python\n# DECISION:NOVEL — No stream processing pattern in this repo.\n# Adapted consumer pattern from Kafka docs.\nasync def consume_events(topic: str):\n```\n\n```typescript\n// DECISION:IFACE — Changed /api/users from array to paginated envelope\n// { data: [], cursor: string }. All frontend callers need update.\nexport async function listUsers(cursor?: string): Promise\u003cPaginatedResponse\u003cUser>> {\n```\n\n```python\n# DECISION:IRREV — Drops legacy_roles column. Data already migrated\n# to roles table (migration 002). Not reversible.\ndef upgrade():\n op.drop_column('users', 'legacy_roles')\n```\n\n```python\n# DECISION:SCOPE — Issue #142 says \"add user filtering\" without specifying\n# fields. Implementing name + email only (fields in list view).\n```\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":1366,"content_sha256":"d8d5bb30e1b2df0be58761ad6cb91403b974d82a4ee87f0f627b69241bd063b6"},{"filename":"references/pre-approval-gate.md","content":"# Pre-approval gate\n\nBefore writing implementation code, produce a PLAN.md with:\n\n- Files you intend to create or modify\n- Any new dependencies, patterns, or abstractions you plan to introduce\n- How you interpreted the task (especially any ambiguities you resolved)\n- Any operations that would be irreversible\n\nWait for human approval of PLAN.md before proceeding. If the task is routine (all changes follow existing patterns, no new dependencies, no ambiguity), note \"Routine task, no pre-approval needed\" and proceed.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":520,"content_sha256":"595805f092b63c601c564413676c3432e903b2638a6f2db9d87a2a7b9d06f717"},{"filename":"references/scope-interpretation.md","content":"# Scope interpretation\n\nWhen a task is ambiguous, do not silently pick an interpretation. Instead:\n\n1. State the ambiguity explicitly\n2. List the possible interpretations (2-3 max)\n3. State which one you would choose and why\n4. Proceed with your chosen interpretation but flag it in the decision log as part of the pull-request description under SCOPE\n\nIf the task references concepts or components you cannot find in the codebase, stop and flag this rather than inventing something.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":484,"content_sha256":"fe34d237be108f191a79e344901fddce2a2435ad80d414875d493f9b1f743ac8"},{"filename":"references/security-protocol.md","content":"# Security protocol\n\nNever auto-commit changes to these paths without human review:\n\n- auth/, login/, session/, permission/, rbac/\n- Any file containing crypto, hashing, or token operations\n- Any file that opens network connections or modifies CORS/CSP\n- Any SQL that uses string interpolation or concatenation\n\nWhen modifying these paths, add a SEC section to DECISION_LOG.md explaining:\n\n- What security property you're maintaining or changing\n- What input validation exists\n- What could go wrong if this code has a bug\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":522,"content_sha256":"bf789bfc72e697765f8ede088f6726f53fcdd04bd2bc968c6ab6d6bf082bb14d"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Documenting Decisions","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Checkpoint tags","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Tag","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"When to mark","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ARCH","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"New abstractions, deps, data models, component boundaries — anything that shapes long-term structure.","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SCOPE","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"You resolved an ambiguity in the task by choosing an interpretation.","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"IFACE","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Changed a public API, config schema, CLI flag, env var, or wire format.","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"SEC","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Touched auth, crypto, permissions, network exposure, or input validation.","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"IRREV","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Created a migration, data deletion, deployment trigger, or external side effect.","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"NOVEL","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No existing repo pattern to follow — you interpolated from training data.","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Do not mark routine changes (pattern-following, boilerplate, refactoring).","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Format","type":"text"}]},{"type":"paragraph","content":[{"text":"See this skill's ","type":"text"},{"text":"references/","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"decision-markers.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and (if needed) ","type":"text"},{"text":"marker-examples.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"After task completion","type":"text"}]},{"type":"paragraph","content":[{"text":"Generate decision log from markers in changed files and add to PR description:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Decisions requiring review\n- **TAG** `file:line` — explanation\n## Routine (skip review)\n[One-line summary]","type":"text"}]},{"type":"paragraph","content":[{"text":"If an ","type":"text"},{"text":"ARCH","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"IRREV","type":"text","marks":[{"type":"code_inline"}]},{"text":" marker meets the ","type":"text"},{"text":"writing-adrs","type":"text","marks":[{"type":"code_inline"}]},{"text":" bar (hard to reverse, surprising without context, result of a real trade-off), also write the ADR per that skill.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Reconcile driving ticket","type":"text"}]},{"type":"paragraph","content":[{"text":"Work driven by ticket → update it before close: fold in deviations, mid-session scope, decisions above (or their ADR/glossary refs). Per ","type":"text"},{"text":"to-tickets","type":"text","marks":[{"type":"code_inline"}]},{"text":" reproducibility invariant: replayed issue stream builds final state, not first draft.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Diff classification mode","type":"text"}]},{"type":"paragraph","content":[{"text":"When user requests review of diff, classify each hunk as one of the six tags or ","type":"text"},{"text":"ROUTINE","type":"text","marks":[{"type":"code_inline"}]},{"text":". Present as ","type":"text"},{"text":"File: path — TAG","type":"text","marks":[{"type":"code_inline"}]},{"text":" with line ranges.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Reference files","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/canary-signals.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — CI scripts for automated checkpoint detection (repo setup, not runtime).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"references/marker-examples.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" — example markers in multiple languages.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"other files in references are only relevant if explicitly mentioned in AGENTS.md or requested by the user.","type":"text"}]}]}]}]},"metadata":{"date":"2026-11-02","name":"documenting-decisions","author":"@skillopedia","source":{"stars":1,"repo_name":"skills","origin_url":"https://github.com/pandoscope/skills/blob/HEAD/original/documenting-decisions/SKILL.md","repo_owner":"pandoscope","body_sha256":"bbe58ddca959144a475e8c8be7c0cdcfe9d3d2e6eb881f32651b572ffda0a84f","cluster_key":"a7a11b9c6c9a4171cb16e46ea8935dfd211be1e55a5f86425f3e4f8754e4adb9","clean_bundle":{"format":"clean-skill-bundle-v1","source":"pandoscope/skills/original/documenting-decisions/SKILL.md","text_bytes":15867,"source_commit":"925fe390437f8371bc1784b5b6890f28db70835e","skills_sh_rank":8666,"attachment_count":8,"text_attachments":8,"attachment_storage":"skill_attachments","binary_attachments":0},"cluster_size":1,"skill_md_path":"original/documenting-decisions/SKILL.md","import_metadata":{"date":"2026-11-02","author":"@skillopedia","version":"v1","category":"software-engineering","category_label":"Engineering"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"software-engineering","import_tag":"skills-sh-top20k-2026-11","description":"Routes human attention to decisions that matter in agent-generated code. Active during planning, implementing, fixing. Defines when and how to place DECISION markers in code comments. Also applies when reviewing a diff/PR on request."}},"renderedAt":1793676261565}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.