security-hooks/.crosslink/rules/tracking-normal.md

Crosslink Task Management

Create issues before starting work to keep things organized and enable context handoff between sessions.

Creating Issues

• Use crosslink quick "title" -p <priority> -l <label> for one-step create+label+work.
• Issue titles should be changelog-ready: start with a verb ("Add", "Fix", "Update"), describe the user-visible change.
• Add labels for changelog categories: bug/fix → Fixed, feature/enhancement → Added, breaking → Changed, security → Security.
• For multi-part features: create parent issue + subissues. Work one at a time.
• Add context as you discover things: crosslink issue comment <id> "..."

Labels for Changelog Categories

• bug, fix → Fixed
• feature, enhancement → Added
• breaking, breaking-change → Changed
• security → Security
• deprecated → Deprecated
• removed → Removed
• (no label) → Changed (default)

Quick Reference

# One-step create + label + start working
crosslink quick "Fix auth timeout" -p high -l bug

# Or use create with flags
crosslink issue create "Add dark mode" -p medium --label feature --work

# Multi-part feature
crosslink issue create "Add user auth" -p high --label feature
crosslink issue subissue 1 "Add registration endpoint"
crosslink issue subissue 1 "Add login endpoint"

# Track progress
crosslink session work <id>
crosslink issue comment <id> "Found existing helper in utils/" --kind observation

# Close (auto-updates CHANGELOG.md)
crosslink issue close <id>
crosslink issue close <id> --no-changelog    # Skip changelog for internal work
crosslink issue close-all --no-changelog     # Batch close

# Quiet mode for scripting
crosslink -q create "Fix bug" -p high  # Outputs just the ID number

Session Management

Sessions auto-start. End them properly when you can:

crosslink session work <id>              # Mark current focus
crosslink session end --notes "..."      # Save handoff context

End sessions when: context is getting long, user indicates stopping, or you've completed significant work.

Handoff notes should include: what was accomplished, what's in progress, what's next.

Typed Comments (REQUIRED)

Every crosslink comment MUST include --kind to categorize the comment for audit trails. This is not optional.

Kinds: plan, decision, observation, blocker, resolution, result, handoff

Minimum required comments per issue:

1. --kind plan — before writing code (what you intend to do)
2. --kind result — before closing (what you delivered)

Also required when applicable:

• --kind decision — when choosing between approaches
• --kind blocker / --kind resolution — when blocked and unblocked
• --kind observation — when you discover something noteworthy

crosslink issue comment <id> "Will refactor auth module to use middleware pattern" --kind plan
crosslink issue comment <id> "Chose middleware over decorator — matches existing patterns" --kind decision
crosslink issue comment <id> "Auth module refactored, 12 tests pass" --kind result

You cannot omit --kind. Even for brief comments, categorize them. The audit trail depends on it.

Priority Guide

• critical: Blocking other work, security issue, production down
• high: User explicitly requested, core functionality
• medium: Standard features, improvements
• low: Nice-to-have, cleanup, optimization

Dependencies

crosslink issue block 2 1     # Issue 2 blocked by issue 1
crosslink issue ready         # Show unblocked work

Large Implementations (500+ lines)

1. Create parent issue: crosslink issue create "<feature>" -p high
2. Break into subissues: crosslink issue subissue <id> "<component>"
3. Work one subissue at a time, close each when done

Context Window Management

When conversation is long or task needs many steps:

1. Create tracking issue: crosslink issue create "Continue: <summary>" -p high
2. Add notes: crosslink issue comment <id> "<what's done, what's next>"