{
  "schema_version": 2,
  "kind": "shortening-method",
  "format": "agent-skill",
  "id": "code-comments",
  "name": "Code comments",
  "category": "Technical",
  "summary": "Remove code narration while retaining intent, invariants, and warnings.",
  "use_cases": [
    "Inline comments",
    "Implementation notes"
  ],
  "word_count": 152,
  "url": "https://sho.rten.it/methods/code-comments/",
  "instructions_url": "https://sho.rten.it/methods/code-comments/SKILL.md",
  "skill_url": "https://sho.rten.it/methods/code-comments/SKILL.md",
  "json_url": "https://sho.rten.it/methods/code-comments/llms.txt",
  "plain_text_url": "https://sho.rten.it/methods/code-comments/prompt.txt",
  "license": "MIT",
  "sources_url": "https://sho.rten.it/sources/#code-comments",
  "skill_name": "code-comments",
  "skill_description": "Remove code narration while retaining intent, invariants, and warnings. Use for Inline comments, Implementation notes.",
  "agents_md_url": "https://sho.rten.it/methods/code-comments/AGENTS.md",
  "sources": [],
  "instructions": "Condense the supplied code comments while leaving the code unchanged. Prefer the reason, constraint, or surprising behavior that a future maintainer cannot see directly in the adjacent code.\n\nDelete narration that only repeats an obvious operation. Keep comments that explain an invariant, ordering requirement, units, ownership, compatibility constraint, or a deliberate workaround. Preserve issue references, protocol terminology, uncertainty, and the condition under which a workaround can be removed. Do not shorten a public API contract as though it were a disposable implementation comment.\n\nCombine adjacent comments about one reason. Use direct sentences or short fragments where their relationship to the code is clear. Keep identifiers and annotation markers such as TODO exactly unless the user explicitly asks to change them.\n\nReturn the revised comments with enough unchanged code context to locate them, if supplied. Do not refactor code, invent intent, resolve a TODO, or replace an uncertain explanation with a confident claim.",
  "example": {
    "context": "Re-entrant subscription cleanup",
    "before": "// We first remove the subscription from the map before we call close().\n// This order is important because close() can synchronously invoke onClose.\n// When that callback runs it looks up the subscription in this same map.\n// If the entry were still present, the callback could try to close it again.\nsubscriptions.delete(id);\nsubscription.close();",
    "after": "// Remove before close(): it can call onClose synchronously,\n// which could find this entry and close it again.\nsubscriptions.delete(id);\nsubscription.close();",
    "must_preserve": [
      "Code unchanged: subscriptions.delete(id); then subscription.close();",
      "close() can invoke onClose synchronously",
      "Map lookup can trigger a second close if entry remains",
      "Ordering requirement retained"
    ],
    "kind": "illustrative",
    "omitted": [
      "Step-by-step framing (\"We first\" and \"This order is important\") around the preserved callback warning."
    ]
  }
}