Comment feature

comment-feature — bounded feature delivery through a comm

Use this for a feature whose goal and acceptance are defined. Use comment-spec when a material goal or product fork still needs shaping; use comment-prototype when the human wants to see an exploratory change first.

This skill composes delivery-methodology, worklog, drive-plan, review-loop, steer, and ship. Before using one, read its full SKILL.md (its SKILL.md).

Project Root and identity

Direct feature work uses its worklog as Project Root. When a Spec or existing Project Root URL is supplied, preserve it and make the worklog a child. A prototype promotion reuses and upgrades the existing worklog/branch.

Keep the working Comment.io route and identity for every created artifact, edit, and comment. Invoke comment-identity only immediately before an uncredentialed direct-REST write. Never switch to an ambient registered or Botlets profile.

Workflow

1. Choose topology before editing. Read delivery-methodology plus the repo's AGENTS.md/CLAUDE.md and linked delivery/testing docs. Record one:

   • direct task branch for a complete independently shippable change; or
   • controlled lift for foundational work with unsafe intermediate states.

   Feature flags require a clean bounded activation seam. Do not use them to preserve two architectures, dual writes, duplicated state, or broad compatibility scaffolding.

2. Open or inherit one worklog. Put the plan in its body unless a genuinely multi-slice initiative benefits from a separate Plan comm. Post material review/decision points as comments. A newly added visible body @mention and a comment @mention both notify; use one surface for the handoff so the recipient is not pinged twice. On direct REST, that agent-authored notifying comment must include the structured notify brief. @mention the relevant human only when the active route exposes a valid handle; otherwise make it a general comment, hand the human the worklog URL directly, and never invent a handle.

3. Understand the affected system. Use read-only explorers when parallel investigation will reduce uncertainty. Record conclusions, not transcripts. Start from the real user journey and implement the simplest useful behavior that can validate whether users love it. Do not add speculative enterprise hardening, abstraction, or edge-case machinery without evidence or a current requirement.

4. Plan bounded delivery slices. Each has acceptance, explicit base/head intent, invariants, focused evidence, and promotion dependency. Phases may organize work but are not automatic review, staging, or steering gates. Consider alternatives only for a material choice; record the decision and rejected option briefly.

5. Review the plan proportionally. Skip review for an obvious routine plan. Otherwise use one reviewer; add a sensitive-risk lens only when warranted. Do not run fresh panels until silent. An inherited approved Spec is the non-technical design; do not recreate it.

6. Execute with drive-plan. Implement one bounded delta at a time, run focused checks, update the worklog at material milestones, and invoke review-loop only at a delivery-slice or changed-invariant boundary.

7. Record receipts. A lift worklog keeps the ordered receipt ledger required by delivery-methodology. A direct candidate records its final base/head, evidence, findings, declines, and residual risk.

8. Ship the right boundary. Use ship in direct, lift-slice, or lift-promotion mode. Direct candidates and frozen promotions get complete affected certification plus one official review; lift slices get focused delta evidence and receipts. Stop at technically ready unless merge authority is explicit; when it is, merge and verify ancestry.

Pragmatic done

The feature boundary is done when acceptance passes, required evidence passes, no known severity-blocking defect remains, mandatory repo rules hold, and residual risks/follow-ups are recorded. Optional polish and unrelated cleanup become follow-ups.

Keep reviews and fixes locked to the declared feature boundary. Unrelated bugs follow delivery-methodology's issue-and-continue protocol; never turn this feature branch into a surprise cleanup job.

Outputs

• One current Project Root/worklog with topology, plan, status, decisions, receipts, open questions, and PR links.
• A technically ready direct PR, lift-slice PR, or final promotion PR.
• Separate design/Plan/ADR comms only when a real audience or durable architecture decision needs them. A proposed ADR becomes accepted only after the change reaches the release branch.

Content vs comments

Current plan, status, decisions, receipts, summary, and open questions belong in the body. Review batches, steering exchanges, and escalations belong in concise comments. Do not post one comment per reviewer.

Repo config

Read AGENTS.md (else CLAUDE.md) and its linked delivery/testing docs for topology, focused checks, final certification, PR/merge, and preview rules. If missing, infer the safe minimum and offer comment-init.

Comment.io API

Use the current worklog/Project Root and its working Comment.io route first. Resolve and freeze $BASE for the whole workflow in this order: the supplied comm's validated final Comment.io origin after any shortlink redirect; the active Comment.io tool/account base URL; an explicitly selected profile's base_url; only when no target context exists, https://comment.io. A shortlink origin is never $BASE; do not switch a staging/custom workflow to production. For direct REST, consult $BASE/llms/reference.txt only when exact API or recovery detail is needed. Fetch $BASE/llms.txt only when no current route works or another focused guide is needed. Invoke comment-identity only before an uncredentialed direct-REST write; never replace a supplied token or tool/browser/connector identity. Don't restate the live contracts here.