# Internal Writing Guide
# Cold Bore Ballistics LLC — Internal Reference
# Classification: Confidential

This guide covers prose and structure for internal communication: Jira tickets, Confluence pages, commit messages, session handoff notes, Slack messages, and internal documentation. It does not cover external or marketing copy — see `OneDrive/ScopeDOPE/04_-_Highly_Confidential/Marketing_Guide/SCOPEDOPE_MARKETING_GUIDE.md` for that.

---

## 1. Voice and Tone

**Direct.** State the decision, then the reason, then the implication. Do not bury the action item in context.

**Specific.** "The container app scales to zero after 5 minutes of inactivity" is better than "the container app is configured to scale." Vague statements force the reader to go elsewhere for the specifics.

**Economical.** Every sentence should earn its place. If removing it would not change the meaning, remove it.

**Context-complete.** Write as if the reader has no memory of prior sessions or conversations. This is not politeness — it is a practical requirement. Claude Code loses context between sessions. Future contributors cannot access Slack history. A buyer's engineering team cannot access your memory. Write so that none of this matters.

---

## 2. Commit Messages

Format is governed by CBB_SDLC.md §3 (conventional commits). This section adds writing guidance.

### Subject line (≤72 characters, imperative mood)

- `type(scope): description` — e.g. `feat(ballistics):`, `fix(ui):`, `docs(M365):`
- Imperative mood: "add", "fix", "remove" — not "added", "fixes", "removing"
- Specific: "fix G7 drag table calibration factor" not "fix ballistics bug"
- No trailing period

### Body (use it when WHY is not obvious)

- Explain why, not what — the diff shows what
- Reference the spec section where applicable: "per §6.3 atmospheric model"
- For bug fixes: describe the root cause, not just the symptom
- Wrap lines at 72 characters

### What not to include

- Engine internals or DOPE-Blend algorithm details — git history is permanent and hosted on GitHub
- Full Jira URLs — use the key only (`DOPE-42`) if referencing an issue

---

## 3. Jira Tickets

### Summary (title)

- ≤80 characters
- Verb-first, imperative: "Add hardware target labels to DOPE issues" not "Hardware target labels"
- Specific enough to understand without reading the description
- No trailing period

### Description

Structure every description as: **Context → What → Acceptance criteria**

1. One or two sentences of context: why this matters, what problem it solves
2. What specifically needs to be done (not a restatement of the title)
3. A checklist of observable outcomes that define "done"

**Example:**

> Multiple DOPE issues are hardware-specific but there is no machine-queryable way to filter by device. Structured labels enable JQL queries like `labels = hw:niimbot_b21_pro`.
>
> Add labels `hw:weatherflow_tactical`, `hw:niimbot_b1`, `hw:niimbot_b21_pro`, `hw:btmeter_bt100` to all qualifying open DOPE issues.
>
> **Acceptance criteria:**
> - [ ] All hardware-specific DOPE issues have at least one `hw:` label
> - [ ] `JQL: project = DOPE AND labels = hw:niimbot_b21_pro` returns the correct issue set

### Fields — fill on creation, not later

- **Repository** custom field: required on every DOPE and CBB issue
- **Fix version**: set on every issue targeting a specific release
- **Labels**: `release-blocking-1.0`, `release-checklist`, `hw:*`, or other applicable labels (the release-blocking label is version-scoped — e.g. `release-blocking-1.0`)
- **Priority**: set honestly — do not default everything to Medium

### What not to put in Jira

Atlassian is a third-party-hosted service. Never put in Jira:

- Engine internals or DOPE-Blend algorithm details
- Credentials, keys, or security-sensitive configuration values
- NDA-protected content received from partners
- Financial projections

---

## 4. Confluence Pages

### Structure

- Open with a one-paragraph purpose statement: what is this page, who is it for
- Use Confluence heading styles (Heading 1 for top-level, Heading 2 for subsections)
- Tables for reference data; numbered lists for procedures; bulleted lists for reference items
- One topic per page — if a page covers two things, split it

### Content rules

- Present tense for reference content: "The ACR is named `crcbbprod`"
- Imperative for procedures: "Run `az acr login`"
- Date-stamp time-sensitive state: "As of 2026-06-04, the VM is pending Bpsv2 quota approval"
- Link to OneDrive documents rather than duplicating their content — Confluence is the front door, OneDrive is the filing cabinet

### What belongs in Confluence vs OneDrive

| Type | Home |
|---|---|
| Operational summary a buyer or new hire should read first | Confluence (SCOPE or CBBOPS space) |
| Detailed runbook, rebuild guide, architecture reference | OneDrive/03_-_Confidential/ |
| Trade secret content (engine internals, DOPE-Blend, SPEC) | OneDrive/04_-_HC only — never Confluence |
| Working artifacts (REQUIREMENTS.md, Branch SPEC) | `<org-root>/docs-working/` (one level above repos — never inside a git repo) |

---

## 5. Slack

### Channel usage

- Repo channels (`#scopedope-android`, `#cbb-infra`, etc.) are GitHub notification feeds — do not start discussions in them
- Product and operational discussion belongs in `#scopedope_general` or `#all-cold-bore-ballistics-llc`
- Reply in threads — do not post a new top-level message when replying to one

### Message style

- For decisions and announcements: state the decision in the first sentence, reasons after
- For questions: include enough context that the reader does not need to ask clarifying questions before they can answer
- Keep sensitive material out of Slack: no engine internals, no financial projections, no NDA content, no credentials, no trade-secret methodology

---

## 6. Session Handoff Documents (REQUIREMENTS.md)

Follow the template in SDLC §6.3 exactly. The purpose of REQUIREMENTS.md is to allow any session — human or AI — to resume work without prior context.

### Writing rules per section

**Task:** One paragraph, present tense, specific enough that a reader with no memory can understand what is being implemented and why. Do not say "continue the work" — describe the work.

**Relevant Spec Sections:** Only sections that directly affect the current task. Not the full spec — that is trade secret content and context overhead.

**Acceptance Criteria:** Must be testable and observable. "Builds without errors" is not an acceptance criterion. "`:shared:ballistics:jvmTest` passes" is. "The DOPE entry screen saves and re-loads correctly on a physical device" is.

**Session Notes:** Updated at the end of every session with what was completed and what remains. This is the most important section — it is the only continuity between sessions.

---

## 7. Numbers, Units, and Terms

### Units

- SI units in all technical content: meters, kilograms, Pascals, meters per second
- US customary in user-facing copy where the audience expects it: yards, feet, grains, inches of mercury
- Ballistics: "mil" consistently — not "mrad" — this is the unit the ScopeDOPE user base uses

### Currency

Always use the explicit symbol: $29.99, not "29.99". In Markdown files, escape the dollar sign: `$29.99`.

### Dates

ISO 8601: `2026-06-04`. Do not use relative dates ("Thursday", "next week") in any document meant to be read in the future — always convert to absolute dates.

### Product names and trademark usage

See `BRAND_LEGAL_LANGUAGE_GUIDE.md`.

---

## 8. What Not to Write

- Do not summarize what you just did in a commit message — the diff does that
- Do not write "as per" — just state the thing
- Do not write "TODO" without a Jira ticket key — orphaned TODOs disappear into git history
- Do not use passive voice to avoid assigning responsibility — "the script was run" tells nobody anything useful
- Do not write "etc." — if the list is incomplete, either complete it or say explicitly that it is non-exhaustive

---

## Document Control

| Field | Value |
|---|---|
| **Document owner** | `jschwefel@coldboreballisticsllc.com` |
| **Classification** | Confidential (03_-_Confidential/) |
| **Location** | `OneDrive/CBB_Corporate/03_-_Confidential/Style_Guides/INTERNAL_WRITING_GUIDE.md` |
| **Cross-references** | `TECHNICAL_DOCUMENTATION_GUIDE.md`; `BRAND_LEGAL_LANGUAGE_GUIDE.md` |
| **Created** | 2026-06-05 |
| **Last updated** | 2026-06-09 |
| **Next full review due** | 2027-06-05 |

---

## Revision Control Block

| Rev | Date | Changed By | Reviewed By | Approved By | Summary |
|-----|------|------------|-------------|-------------|---------|
| 0.9 | 2026-06-05 | jschwefel | — | — | Initial release |
| DRAFT | 2026-06-09 | Claude Code | — | — | Updated §3 Jira label guidance: `launch-blocking`→`release-blocking-1.0` (version-scoped) + added `release-checklist`, matching the standardized DOPE/CBB tracker convention. Removed non-standard `# Last Updated` header line (per TECHNICAL_DOCUMENTATION_GUIDE §7). Fixed Marketing_Guide cross-ref path namespace. |
