Tracey

Tracey

Add proper spec annotations to code using Tracey's requirement tracking system.

Overview

Tracey maintains traceability between specification requirements and code. This skill helps add proper r[impl req.id] and r[verify req.id] annotations to code, find which requirements need implementation or testing, and understand Tracey annotation syntax.

Primary Interface: Use Tracey MCP tools (tracey_status, tracey_uncovered, tracey_untested, tracey_stale, tracey_rule, tracey_unmapped, tracey_validate, tracey_config) to discover requirements and validate coverage. The MCP tools provide self-documenting output showing which prefixes to use and what requirements need work.

When to Use

Use this skill when:

• Working with a project that has .config/tracey/config.styx
• User asks to "add spec annotations" or "annotate with requirements"
• Need to find which requirements are uncovered or untested
• Writing code that implements spec requirements
• Writing tests that verify spec requirements

Quick Reference: MCP Tools

Tip: Start with tracey_status to see what prefix to use (e.g., r[...] vs shm[...]), then use tracey_uncovered or tracey_untested to find work that needs doing.

Workflow: Adding Annotations

Step 1: Check Configuration and Prefixes

Use the tracey_status MCP tool to see configured specs and their prefixes:

tracey_status

This shows:

• Which specs are configured (e.g., rapace, shm, rust)
• What prefix to use for each (e.g., r[...], shm[...], rs[...])
• Current coverage percentages by implementation

Example output:

## Configured Specs

- **rapace** (prefix: `r`)
  - When annotating code, use: `r[impl rule.id]` or `r[verify rule.id]`

- **shm** (prefix: `shm`)
  - When annotating code, use: `shm[impl rule.id]` or `shm[verify rule.id]`

Step 2: Find Relevant Requirements

Use Tracey MCP tools to discover which requirements need work:

Find requirements without implementation:

tracey_uncovered --spec_impl "rapace/rust"

Find requirements without tests:

tracey_untested --spec_impl "rapace/typescript"

Get details about a specific requirement:

tracey_rule "message.hello.timing"

See which code lacks requirement references:

tracey_unmapped --path "src/auth/"

Step 3: Add Annotations

Add comments above relevant code using PREFIX[VERB REQ] syntax:

// r[impl auth.token.validation]
fn validate_token(token: &str) -> bool {
    // implementation
}

For tests:

// r[verify auth.token.validation]
#[test]
fn test_token_validation() {
    assert!(validate_token("valid"));
}

Step 4: Validate

Use tracey_status to verify your annotations were detected and coverage improved:

tracey_status

Check that the implementation/verification percentages increased for your target spec/impl combination.

Annotation Syntax

Supported Verbs

• impl - This code implements the requirement (default if verb omitted)
• verify - This code tests/verifies the requirement
• depends - This code must be reviewed if the requirement changes
• related - Loosely connected, shown when reviewing related code

Language-Specific Examples

Rust:

// r[impl database.connection]
fn connect_to_db() -> Result<Connection> { ... }

/// r[verify database.connection]
#[test]
fn test_connection() { ... }

TypeScript:

// r[impl api.error.format]
function formatError(code: number, message: string) { ... }

// r[verify api.error.format]
test('error format', () => { ... });

Python:

# r[impl auth.validation]
def validate_user(token: str) -> bool:
    pass

# r[verify auth.validation]
def test_validate_user():
    pass

Swift:

// r[impl session.timeout]
func cleanupExpiredSessions() { ... }

// r[verify session.timeout]
func testSessionTimeout() { ... }

Common Patterns

Multiple Requirements

One implementation can satisfy multiple requirements:

// r[impl auth.validation]
// r[impl auth.rate-limiting]
fn validate_with_rate_limit() { ... }

Generated Code

Annotate generators, not generated code:

// r[impl codegen.service-dispatch]
fn generate_dispatcher(service: &ServiceDetail) -> String {
    // Code generator that produces dispatchers
}

Partial Implementation

Use clear context when one requirement has multiple implementing functions:

// r[impl database.connection] - connection pooling
fn create_pool() { ... }

// r[impl database.connection] - connection lifecycle
fn close_connection() { ... }

Configuration Example

Note: Instead of manually reading the config file, use tracey_status to see configured specs, prefixes, and implementations.

Typical .config/tracey/config.styx:

specs (
    {
        name my-project
        prefix r
        include (docs/spec/**/*.md)
        impls (
            {
                name rust
                include (
                    crates/**/*.rs
                )
                exclude (target/**)
            }
            {
                name typescript
                include (src/**/*.ts)
            }
        )
    }
)

Key fields:

• prefix - Used in annotations (e.g., r[...])
• include (spec) - Glob patterns for spec markdown files, as a sequence (...)
• impls - Sequence of implementation blocks
• include (impl) - Glob patterns for source files to scan, as a sequence (...)
• exclude (impl) - Glob patterns to exclude, as a sequence (...)

Troubleshooting

Error: Unknown prefix

• Check the prefix in .config/tracey/config.styx
• Ensure annotations use the correct prefix

Requirements not found

• Verify requirement IDs match exactly (case-sensitive, dot-separated)
• Check that spec markdown files are in the configured include paths

Annotations not detected

• Ensure annotations are in comments (not strings)
• Check that source files match the include patterns in config

Reference Documentation

For detailed information about Tracey's implementation, configuration schema, and tooling, see the references/tracey-spec.md file bundled with this skill.

Source: bearcove/tracey — distributed by TomeVault.