Diff: reference/style-guide-ticket-comment.es
From 1c02ec1 to 1c02ec1
+0 / −0 lines
| Before | After |
|---|---|
| --- | --- |
| schema: foundry-doc-v1 | schema: foundry-doc-v1 |
| title: "Style guide — ticket comment" | title: "Style guide — ticket comment" |
| slug: style-guide-ticket-comment | slug: style-guide-ticket-comment |
| category: reference | category: reference |
| type: topic | type: topic |
| content_type: topic | content_type: topic |
| quality: complete | quality: complete |
| short_description: "Editorial standards for ticket comments in the platform (COMMS genre): header discipline, what-changed-and-next structure, status field conventions, and when to comment versus when to update the ticket description." | short_description: "Editorial standards for ticket comments in the platform (COMMS genre): header discipline, what-changed-and-next structure, status field conventions, and when to comment versus when to update the ticket description." |
| status: active | status: active |
| bcsc_class: public-disclosure-safe | bcsc_class: public-disclosure-safe |
| last_edited: 2026-05-24 | last_edited: 2026-05-24 |
| editor: pointsav-engineering | editor: pointsav-engineering |
| cites: [] | cites: [] |
| paired_with: style-guide-ticket-comment.es.md | paired_with: style-guide-ticket-comment.es.md |
| --- | --- |
| > A ticket comment records a state change or a decision — not a thought. Every comment advances the ticket. | > A ticket comment records a state change or a decision — not a thought. Every comment advances the ticket. |
| A **ticket comment** (COMMS genre) is a structured update on an issue, task, or work item. It is addressed to anyone who reads the ticket's history after the comment is posted. Unlike a [[style-guide-chat|chat message]] (which is synchronous and ephemeral), a ticket comment is a permanent record and may be read months later by someone with no context from the thread. This article is the human-facing standard; the machine-readable counterpart lives in `service-disclosure/templates/ticket-comment.toml`. | A **ticket comment** (COMMS genre) is a structured update on an issue, task, or work item. It is addressed to anyone who reads the ticket's history after the comment is posted. Unlike a [[style-guide-chat|chat message]] (which is synchronous and ephemeral), a ticket comment is a permanent record and may be read months later by someone with no context from the thread. This article is the human-facing standard; the machine-readable counterpart lives in `service-disclosure/templates/ticket-comment.toml`. |
| ## When to use this template | ## When to use this template |
| Write a ticket comment when: | Write a ticket comment when: |
| - The status of the work has changed and stakeholders need to know. | - The status of the work has changed and stakeholders need to know. |
| - A decision was made that affects the ticket's scope, timeline, or owner. | - A decision was made that affects the ticket's scope, timeline, or owner. |
| - A blocker has been identified or resolved. | - A blocker has been identified or resolved. |
| - An action was completed and the completion needs to be on record. | - An action was completed and the completion needs to be on record. |
| Do not comment to say you are working on the item — update the Status field instead. Do not post exploratory thoughts or half-formed questions as comments; draft them privately and post when the conclusion is clear. | Do not comment to say you are working on the item — update the Status field instead. Do not post exploratory thoughts or half-formed questions as comments; draft them privately and post when the conclusion is clear. |
| ## Structure | ## Structure |
| **Header block** (before any body text): | **Header block** (before any body text): |
| ``` | ``` |
| Ticket: <ticket-id or title> | Ticket: <ticket-id or title> |
| Status: <new status — Open | In progress | Blocked | Review | Done> | Status: <new status — Open | In progress | Blocked | Review | Done> |
| ``` | ``` |
| | Section | Purpose | | | Section | Purpose | |
| |---|---| | |---|---| |
| | **What changed** | One to three sentences: the specific change in state, decision made, or fact established. Name the artifact, commit SHA, or decision explicitly. | | | **What changed** | One to three sentences: the specific change in state, decision made, or fact established. Name the artifact, commit SHA, or decision explicitly. | |
| | **Next** | The concrete next step, with owner. A ticket comment with no "Next" is a dead end — the reader cannot act on it. If the ticket is Done, "Next" is "Closed." | | | **Next** | The concrete next step, with owner. A ticket comment with no "Next" is a dead end — the reader cannot act on it. If the ticket is Done, "Next" is "Closed." | |
| ## Register and tone | ## Register and tone |
| Factual and brief. Past tense for what changed ("Committed X at hash Y"); present or future for next steps ("Owner: Jennifer; due 2026-06-01"). No hedges — either the state changed or it did not. | Factual and brief. Past tense for what changed ("Committed X at hash Y"); present or future for next steps ("Owner: Jennifer; due 2026-06-01"). No hedges — either the state changed or it did not. |
| Status field values are a closed set: `Open`, `In progress`, `Blocked`, `Review`, `Done`. No custom values. | Status field values are a closed set: `Open`, `In progress`, `Blocked`, `Review`, `Done`. No custom values. |
| Sentence-length budget: one to two sentences per section. If "What changed" needs more than three sentences, the change is complex enough to warrant a brief or a memo — reference it from the ticket comment rather than writing it inline. | Sentence-length budget: one to two sentences per section. If "What changed" needs more than three sentences, the change is complex enough to warrant a brief or a memo — reference it from the ticket comment rather than writing it inline. |
| ## See also | ## See also |
| - [[style-guide-chat|Style Guide — Chat]] | - [[style-guide-chat|Style Guide — Chat]] |
| - [[style-guide-meeting-notes|Style Guide — Meeting Notes]] | - [[style-guide-meeting-notes|Style Guide — Meeting Notes]] |
| - [[language-protocol-substrate|Language Protocol Substrate]] | - [[language-protocol-substrate|Language Protocol Substrate]] |