# Ccg Annotate

> Author, refine, and verify CCG annotations such as @intent, @domainRule, @sideEffect, @mutates, @index, and @see. Use when adding business meaning to code, improving annotation-aware code or documentation retrieval, fixing annotation lint findings, checking supported tag syntax, or documenting operational contracts. Do not use for generated Markdown editing or annotations that merely restate symbol names.

- Skill: `tae2089/ccg-annotate` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tae2089/ccg-annotate`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tae2089/ccg-annotate/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tae2089 (https://skillmd.com/u/tae2089)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/tae2089/ccg-annotate

---


# ccg-annotate — Annotation Workflow

Add structured business metadata to source comments so graph search and
generated documentation can retrieve intent and operational contracts.

## Retrieval-Aware Tag Selection

Annotations are retrieval features, but they must stay truthful. Use the
specific tag that matches the code's role instead of stuffing keywords into
`@intent`.

| When you see this | Add this |
| ----------------- | -------- |
| File/package/module should be found as one unit | `@index` |
| Public function, handler, CLI command, service method, or UI workflow has a clear purpose | `@intent` |
| Policy, constraint, operational rule, or false-positive/false-negative criterion matters | `@domainRule` |
| DB/file/network/cache/log/process side effect exists | `@sideEffect` |
| Receiver or argument object changes in memory | `@mutates` |
| Caller-facing input/output contract matters | `@requires`, `@ensures` |
| Related implementation must be followed, especially across namespaces | `@see` |

Good retrieval annotations include the words a developer or LLM would naturally
use to ask for the code, while matching the implementation. For example, if a
graph component focuses a resolved `ccg://` node, say `graph viewer`, `ccg ref`,
and `node focus` in the appropriate `@index`/`@intent`. Do not add unrelated
terms just to raise score; broad terms make the wrong files rank higher.

Read [`references/annotation-reference.md`](references/annotation-reference.md)
before using less-common tags, aliases, multiline values, typed JSDoc/YARD
forms, cross-namespace refs, or language-specific comment syntax.

## Annotation Workflow

This is an agent skill workflow, not a `ccg` CLI subcommand. The agent reads and
edits code directly.

### Step 1: Pick targets

- File path → that file only
- Directory → all source files
- **Skip**: vendor, dependencies, and generated code
- Skip tests by default; include a test only when it is itself important domain-contract evidence

### Step 2: Analyze each target

Read the code and determine:

- What it does → first summary line
- File/package discoverability → `@index` when the file itself is a useful search target
- **Why it exists → `@intent`** for meaningful public/workflow entry points
- Business or operational rules → `@domainRule` (must be specific)
- Real side effects → `@sideEffect`
- State changes → `@mutates`
- Caller-facing contracts → `@requires`, `@ensures` when they matter

For cross-namespace behavior, explain the reason in the semantic tag and put the target in `@see`:

```go
// @sideEffect records token validation audit in auth-svc.
// @see ccg://auth-svc/internal/audit/token_audit.go#RecordTokenAudit
```

### Step 3: Write

- Add comments directly above the declaration using the language's documentation-comment syntax
- Preserve accurate human-authored context; update or remove stale, false, or duplicate tags when refinement is requested
- Do not erase non-obvious rationale unless the code contradicts it; report such changes explicitly
- **Skip trivial functions** (getters/setters, obvious one-line wrappers)
- Do not add tags that do not match real behavior
- Do not repeat the same keyword across tags unless each tag adds distinct evidence
- Match the language of existing comments (Korean for Korean codebases, English for English)

### Step 4: Report reindex requirement

Annotations enter the search index only at graph build time. An annotation
written but not rebuilt is invisible to `search` — the most common way to
conclude, wrongly, that "annotations don't work". Do not invoke `ccg-build`
automatically. Report that reindexing is required and that the user must
explicitly name `ccg-build` in a new request before graph refresh.

After an explicitly authorized refresh, representative changed symbols can be
checked with `get_annotation`. Until then, report graph-backed verification as
pending. The parser returns unknown-tag warnings to direct callers, but the
current ingestion discards that warning list and `ccg lint` does not surface it.
Treat the reference tag list as an allowlist; a green lint result alone does not
prove an unknown tag was indexed.

## Quality Example

❌ **Bad annotation**:

```go
// @intent creates a user
func CreateUser(...) {}
```

WHAT only. Function name already tells you that.

✅ **Good annotation**:

```go
// @intent register a normalized account for the onboarding flow
// @domainRule email must be unique across all tenants
// @sideEffect inserts the user and audit record, then sends a verification email
// @mutates input.NormalizedEmail
func CreateUser(input *SignupRequest) error { ... }
```

WHY + business rules + side effects. Code and documentation search become powerful.

## Annotation Priority

Don't annotate everything. Prioritize:

1. **Tier 1**: domain core (auth, payment, billing — business logic)
2. **Tier 2**: frequently searched (entry points, public APIs)
3. **Tier 3**: complex functions (high cognitive load)
4. **Skip**: getters/setters, simple wrappers, generated code

Use `ccg lint` `unannotated` category and pick top-priority functions from there.

## Retrieval Quality Checks

After adding annotations for a feature area, run a few natural-language
retrieve/search probes that match how an LLM or engineer would ask:

```bash
ccg search "graph viewer ccg ref node focus"
```

For MCP/Web UI retrieval, use `search` + `get_doc_content` or Wiki search. If the
expected file is missing, prefer improving the precise `@index`, `@intent`,
`@domainRule`, or `@see` evidence on that file over changing global scoring.

## Closing the Question Loop

When this skill was entered from the `ccg` skill's search failure path — a
plain-language question that came back empty because no recorded reason
answered it — the work is not done until that question succeeds:

1. Annotate the area the question was about (Steps 1–3), writing the
   `@intent`/`@domainRule` in words that answer the question actually asked.
2. Rebuild (Step 4). Without this the re-ask is guaranteed to fail again.
3. Re-ask the **original question, verbatim**, through `search`, and confirm
   the answer now carries reason-matched hits (`reason` and `matched_terms`)
   pointing at the annotated area.

If the re-ask still comes back empty, the recorded reason and the question do
not share vocabulary — revise the annotation's wording, not the search.

## Completion

List annotated files and meaningful tags added or deliberately revised, report
any existing rationale changed, confirm the rebuild ran, verify representative
nodes with `get_annotation`, run retrieval probes for affected concepts, and
report lint plus any unknown-tag risk or unrelated finding without claiming it
was fixed. When the work started from a failed question, state the original
question and what its re-ask returned.