Imported from David-Li0406/meta-skill-evloving (skill-flow/data/skills-refined-36k/skillsmp/linear-audit/SKILL.md). Install upstream with npx skills add David-Li0406/meta-skill-evloving --skill linear-audit. Copyright stays with the author.

linear-audit

collaborative thought partner for Linear workspace optimization. surfaces what matters through dialogue, brings creative edge to light, and orchestrates specialists for deep analysis.

philosophy

"thinking together about what deserves focus, not checking boxes"

the wattenberger insight

linear-audit is NOT a checklist runner. it's the taking in → transforming → sending out cycle:

• taking in: your priorities, passion points, codebase state, issue landscape
• transforming: synthesis against V1 patterns, gap detection, creative opportunity
• sending out: actionable state - enriched issues, disposition decisions, clear next steps

when to use

companion skills

Note: issue-context patterns are now integrated into linear-audit via references/issue-enrichment-templates.md. Use linear-audit for both auditing and per-issue enrichment.

decision tree: conversation vs mechanical

What mode should I use?
├── First interaction with this project today?
│   └── ALWAYS: start with ask-deep (discover context)
├── User says "quick check" or "just counts"?
│   └── quick mode (skip ask-deep, return stats)
├── User provides rich context already?
│   └── confirm understanding, then proceed to specialists
├── User seems uncertain about priorities?
│   └── deeper ask-deep (explore mode)
└── Default
    └── ask-deep start mode → specialists → ask-deep review

decision tree: ask-deep mode selection

Which ask-deep mode for this phase?
├── Session start / first audit?
│   └── start mode: project, goals, constraints
├── Scope unclear / multiple valid approaches?
│   └── scope mode: MVP, success criteria, exclusions
├── Exploring priorities / passion points?
│   └── explore mode: broad → narrow → edge cases
├── Decision point between options?
│   └── choose mode: options with trade-offs
├── Post-specialist validation?
│   └── review mode: validate findings, edge cases
└── Default
    └── start mode

decision tree: creative edge detection

Should I surface creative edge?
├── User mentions "experimental", "sketchy", "not sure"?
│   └── YES: probe deeper - what makes it exciting? what support needed?
├── Issue references unfamiliar pattern/tech?
│   └── YES: "this looks interesting - tell me more"
├── Gap between issue description and codebase reality?
│   └── YES: "I notice a gap - is this intentional exploration?"
├── High energy/passion in user's description?
│   └── YES: follow the energy - this might be the valuable part
├── Multiple approaches mentioned?
│   └── YES: "which feels most alive to you?"
└── Default
    └── listen for signals, ask when curiosity peaks

decision tree: HIL routing

When should I pause for human input?
├── Priority/disposition decision?
│   └── ALWAYS: "should we keep, enrich, or archive this?"
├── Creative edge detected?
│   └── ALWAYS: "tell me more about this direction"
├── Confidence < 7 on recommendation?
│   └── PAUSE: present options, get guidance
├── Gap between user expectation and findings?
│   └── PAUSE: "I expected X but found Y - does this match your sense?"
├── Batch operation (>5 items)?
│   └── CONFIRM: "I'll process these 12 issues - proceed?"
├── Delete/archive recommendation?
│   └── ALWAYS: "these look stale/duplicate - ok to archive?"
└── Proceeding with specialist fanout?
    └── CONFIRM: "ready to analyze code + linear state?"

decision tree: disposition workflow

What should happen to this issue?
├── Has issue-context markers AND fresh (<14 days)?
│   └── status: ready for V1
├── Has markers but stale (>14 days)?
│   └── HIL: "context is stale - refresh or keep as-is?"
├── No markers, well-formed description?
│   └── action: enrich via issue-context
├── Vague (no description, generic title)?
│   └── HIL: "this seems vague - archive, clarify, or keep?"
├── Duplicate of another issue?
│   └── HIL: "duplicate detected - merge or keep separate?"
├── Outdated (old architecture/patterns)?
│   └── HIL: "this references old patterns - archive?"
├── Epic without children?
│   └── HIL: "epic needs breakdown - explore now or backlog?"
└── User says "delete" or "archive"?
    └── action: archive with confirmation

decision tree: V1 template selection

What project type?
├── Convex + Next.js monorepo (arbor, kumori, koto, etc.)?
│   └── template: convex-next-v1
├── Library/utility package (utils)?
│   └── template: library-v1
├── Swift/iOS app (sine-apple)?
│   └── template: swift-v1
├── Slack bot (saya)?
│   └── template: slack-bot-v1
├── CLI tool (agents, layer, outline)?
│   └── template: cli-v1
└── Unknown?
    └── ask: "what does V1 look like for this project?"

decision tree: failure recovery

Specialist returned failure/timeout/low-confidence?
├── Single specialist failed (<25% of roster)?
│   ├── Non-critical specialist (e.g., architecture)?
│   │   └── proceed without, note gap in synthesis
│   └── Critical specialist (e.g., linear-state)?
│       └── retry once with increased timeout
├── Multiple specialists failed (25-50%)?
│   ├── Common cause (e.g., tool unavailable)?
│   │   └── fix tool, retry all failed
│   └── Random failures?
│       └── partial synthesis, flag incomplete, continue
├── Majority failed (>50%)?
│   └── abort audit, report blocked, schedule retry
├── Low confidence (<7) across all?
│   └── escalate: "findings uncertain - want me to dig deeper?"
└── Mixed results (some success, some partial)?
    └── weight partial results at 0.7, include with caveats

decision tree: cross-project coordination

Cross-project exploration is pull-based, not push-based. Stay focused on the current project unless the conversation naturally surfaces a cross-project connection.

Should I look at other projects?
├── User explicitly mentions another project?
│   │   "how does arbor handle this?" / "like in kumori"
│   └── YES: explore that specific project for the specific thing mentioned
│       └── ask first: "want me to look at how arbor handles this?"
├── User references a pattern that sounds familiar?
│   │   "I think we did something similar somewhere"
│   └── MENTION IT: "that sounds like the overlay pattern in saya - want me to check?"
│       └── wait for signal before exploring
├── Issue references shared code explicitly?
│   │   "update @repo/design" / "sync with kumori's approach"
│   └── YES: explore the referenced code
│       └── scope to what's mentioned, don't expand
├── Multi-project audit explicitly requested?
│   │   "audit all my apps" / "compare these projects"
│   └── ask-deep first: "what are you trying to understand across these?"
│       ├── specific pattern? → explore that pattern only
│       ├── general health? → quick stats, no deep dive
│       └── unclear? → "tell me more about what you're looking for"
└── Default
    └── STAY FOCUSED on current project
        └── don't assume cross-project context is useful

why pull-based matters

Some patterns ARE shared across Luke's repos (overlay system, email templates, hooks), but:

• Auth is standardized - Clerk + Convex everywhere, not interesting for cross-project
• Design packages are copies - each repo has its own @repo/design, intentionally
• Patterns evolved differently - that's often the point, not a gap to fix

Cross-project exploration is valuable when:

• User mentions it
• Issue explicitly references another repo
• User says "like in X" or "similar to Y"
• User asks for portfolio-wide view

known shared patterns (reference, don't scan)

If conversation surfaces these, they exist - don't re-discover:

cross-project subagent patterns (when triggered)

Only spawn these when user explicitly requests cross-project work:

Pattern comparison (user asks "how does X do this?"):

cat <<EOF | codex exec - --full-auto -o /tmp/pattern-analysis.json
Explore ~/Developer/arbor/arbor-xyz for modal patterns.

Focus on: how modals handle animation, backdrop, escape key
Compare to what we're doing in current project.

Output JSON: {patterns: [], differences: [], recommendations: []}
EOF

Portfolio quick stats (user asks for overview):

# Only when explicitly requested - don't do this automatically
for REPO in arbor kumori koto webs; do
  linear issue list --team ${REPO^^} --json -q | jq '{repo: "'$REPO'", count: length}'
done

contextual flexibility

The key insight: conversation drives exploration, not automation.

• If user mentions arbor's modals → explore arbor's modals
• If user says "like in kumori" → look at kumori
• If user doesn't mention other projects → don't assume they're relevant
• When uncertain → ask: "want me to check how X handles this?"

decision tree: escalation routing

Should I escalate to human?
├── Disposition affects other teams?
│   └── ALWAYS: "this touches {TEAM} - should I coordinate?"
├── Archiving high-priority issue?
│   └── ALWAYS: "P1/P2 issue flagged for archive - confirm?"
├── Conflicting specialist findings?
│   └── ALWAYS: present conflict, let human resolve
├── Resource conflict detected (same file in multiple issues)?
│   └── PAUSE: "ARB-123 and ARB-456 both touch auth.ts - sequence?"
├── User explicitly delegated authority?
│   └── proceed with lower threshold, report after
├── Confidence < 5 on any critical recommendation?
│   └── ESCALATE: "I'm uncertain about {X} - thoughts?"
└── Time constraint mentioned?
    └── summarize options, recommend, ask for quick approval

decision tree: Linear agent state management

How should I manage Linear state?
├── Starting to work on issue?
│   ├── Move issue to "started" state
│   ├── Set delegate to agent identity
│   └── Emit thought activity: "analyzing {ISSUE}"
├── Analysis in progress?
│   └── Emit thought activities every 10s max
├── Synthesizing findings?
│   └── Emit response activity with AgentActivity (frozen snapshot)
├── Need human input?
│   └── Emit elicitation activity, wait for response
├── Error during processing?
│   └── Emit error activity with details
└── Audit complete?
    ├── Return issue to original state (unless disposition changed it)
    ├── Clear delegate
    └── Emit final response activity

concrete values

modes

workflow

phase 0: collaborative discovery (ask-deep)

this is where the magic happens - understand the human before the mechanical.

## ask-deep: start mode

round 1 (Open):
- "Which project are we thinking about today?" (detect from cwd, offer recent)
- "What's on your mind with {PROJECT}? What draws your attention?"
- Affirmation: acknowledge what they share

round 2 (Reflective + Probe):
- "So the energy is around {X}..." (reflect back)
- "What does 'done' look like for you right now?"
- "Anything feeling sketchy or experimental that excites you?"

round 3 (Summary + Creative Edge):
- "Let me make sure I have this..."
- "I'm curious about {thing they mentioned} - tell me more?"
- "Ready to look at the codebase + issues together?"

key questions to surface:

• What matters most right now?
• What's the creative edge - the experimental, the uncertain?
• What would make this project feel "alive"?
• What's blocking forward motion?

phase 1: context gathering (tools before specialists)

# Codebase state
cd "$PROJECT_PATH"
layer . --format=json -q > /tmp/architecture.json
outline --stats --format=yaml > /tmp/code-structure.yaml
verify --format=summary 2>/dev/null || echo "no tests"
git log --oneline -10

# Linear state
linear issue list --team $TEAM --json -q > /tmp/issues.json
linear issue list --team $TEAM --json -q | jq 'group_by(.state.name) | map({state: .[0].state.name, count: length})'

phase 2: spawn specialists (4-agent fanout)

spawn 4 specialists in parallel for deep analysis:

# Generate parent ID
AUDIT_ID="linear-audit-$(date +%Y%m%d-%H%M%S)-$(openssl rand -hex 4)"

# Start trace
export AGENTS_TRACE_ID=$(trails trail record --agent claude --new-trace --action started --task "linear-audit: $TEAM" --json -q | jq -r '.trace_id')

# Spawn specialists with --await
for SPECIALIST in code-state architecture linear-state v1-gaps; do
  (
    RESULT=$(cat "$AUDIT_DIR/briefs/${SPECIALIST}.md" | \
      agents session start -a copilot -p $TEAM \
        -g "${SPECIALIST}: $TEAM audit" \
        --parent "$AUDIT_ID" \
        --timeout 180 \
        --await \
        --json -q)
    echo "$RESULT" >> "$AUDIT_DIR/results.jsonl"
  ) &
done
wait

phase 3: synthesis + HIL checkpoint

after specialists return, synthesize and pause:

## synthesis checkpoint

I've gathered findings from 4 specialists. Here's what emerged:

### code state
- coverage: {%}, build: {status}
- recent focus: {areas from git log}

### architecture
- {packages} packages, {cycles} cycles
- notable: {interesting patterns or concerns}

### linear state
- {total} issues: {with_context} enriched, {missing} need context
- distribution: {state breakdown}

### creative edge I noticed
- {anything that seemed experimental/exciting}
- {gaps that might be intentional}

**questions for you:**
1. Does this match your sense of where things are?
2. What surprised you? What feels off?
3. {specific question about creative edge}

phase 4: disposition decisions (interleaved HIL)

for each category of issues, pause for guidance:

## disposition decisions

### issues needing enrichment ({count})
{list top 5}
→ "proceed with issue-context enrichment?"

### potentially stale ({count})
{list}
→ "refresh, keep as-is, or archive?"

### vague/unclear ({count})
{list}
→ "clarify together, archive, or keep?"

### ready for V1 ({count})
{list}
→ "these look good - confirm?"

phase 5: execute dispositions

# Enrich approved issues
for ISSUE in "${ENRICH_QUEUE[@]}"; do
  echo "Enriching $ISSUE..."
  # invoke issue-context skill
  sleep 2  # rate limit
done

# Archive approved issues
for ISSUE in "${ARCHIVE_QUEUE[@]}"; do
  linear issue edit $ISSUE --state "Canceled"
done

# Record completion
trails trail record --agent claude --trace-id $AGENTS_TRACE_ID \
  --action completed \
  --task "linear-audit: $TEAM - $ENRICHED enriched, $ARCHIVED archived" \
  --confidence $CONFIDENCE

phase 6: closing synthesis (ask-deep review)

## ask-deep: review mode

round 1:
- "Here's what we accomplished today..."
- "Does this feel like the right state?"
- "Anything we should have caught but didn't?"

round 2:
- "What's the next pull you feel - where to focus next?"
- "When should we revisit this?"

orchestration: 4-specialist fanout

specialist roster

specialist execution patterns

Code State Specialist:

verify --coverage --json -q | jq '.summary'
pnpm build 2>&1 | tail -20
git log --oneline -20
outline --diff=HEAD~10 --format=yaml

Architecture Specialist:

layer . --format=json -q
layer . --check-cycles
outline --unused -r
layer . --mode=files --format=mermaid > /tmp/arch.mmd

Linear State Specialist:

linear issue list --team $TEAM --json -q
# Check context markers per issue
linear issue list --team $TEAM --json -q | jq 'group_by(.state.name) | map({state: .[0].state.name, count: length})'

V1 Gaps Specialist:

# Compare against V1 template
# Input: code, architecture, linear findings + V1 template
# Output: delta list with prioritized gaps

tool integration

trails integration

persist audit sessions for continuity:

# Start trace
export AGENTS_TRACE_ID=$(trails trail record --agent claude --new-trace --action started --task "linear-audit: $TEAM" --json -q | jq -r '.trace_id')

# Progress
trails trail record --agent claude --trace-id $AGENTS_TRACE_ID --action progress --task "specialists complete" --confidence 7

# Complete with gist
trails trail record --agent claude --trace-id $AGENTS_TRACE_ID --action completed --task "$TEAM: $READY ready, $GAPS gaps" --confidence 9 --gist

# Replay for Slack
trails trail replay --trace-id $AGENTS_TRACE_ID --format slack | slack agent post -a claude -c agents -w saya

V1 templates

V1 = "ready for autonomous execution". templates define the bar.

convex-next-v1

name: convex-next-v1
applies_to: [arbor, kumori, koto, webs, squish, pal, saya]

code:
  test_coverage: 80%
  build: passing
  types: clean

architecture:
  cycles: none
  dead_code: <5%

linear:
  all_issues_have_context: true
  context_freshness: <14 days
  no_vague_issues: true

docs:
  agents_md: present and accurate

library-v1

name: library-v1
applies_to: [agents-cli, layer, outline, verify, trails]

code:
  test_coverage: 90%
  build: passing
  types: strict

docs:
  readme: comprehensive
  api_docs: generated

cli-v1

name: cli-v1
applies_to: [agents, layer, outline, verify, slack, linear]

code:
  test_coverage: 85%
  build: passing

cli:
  help_text: comprehensive
  error_messages: actionable
  json_output: all commands

docs:
  rules_md: present in ~/.agents/rules/

team mapping

Note: Use full team name with linear CLI (e.g., --team ARBOR not --team ARB).

output contract

{
  "mode": "full | quick | enrich | report",
  "status": "success | partial | blocked",
  "summary": "collaborated on ARB linear state - 12 enriched, 3 archived, creative edge on ACP protocol surfaced",
  "confidence": 8,
  "inputs": {
    "team": "ARB",
    "project_path": "~/Developer/arbor/arbor-xyz",
    "project_type": "convex-next",
    "ask_deep_rounds": 3
  },
  "artifacts": [
    { "type": "file", "path": "~/.agents/audits/ARB-20250122/AUDIT.md", "status": "created" }
  ],
  "sources": {
    "prompts": [],
    "files_read": ["issues.json", "architecture.json"]
  },
  "findings": {
    "code_state": { "coverage": 82, "build": "passing" },
    "architecture": { "cycles": 0, "dead_code_pct": 3 },
    "linear_state": { "total": 45, "with_context": 32, "stale": 8, "none": 5 },
    "v1_gaps": { "blockers": 2, "gaps": 5 },
    "creative_edge": ["ACP protocol exploration", "gen-ui experiments"]
  },
  "disposition": {
    "enriched": ["ARB-123", "ARB-456"],
    "archived": ["ARB-789"],
    "kept": ["ARB-101"]
  },
  "ask_deep_synthesis": {
    "priorities": ["ACP agent integration", "test coverage"],
    "passion_points": ["real-time collaboration", "daemon integration"],
    "creative_edge": "ACP protocol feels most alive",
    "next_pull": "focus on agent spawning E2E"
  },
  "v1_ready": false,
  "blockers": ["5 issues missing context"],
  "next_steps": ["run issue-context on queue", "revisit in 1 week"],
  "gist_url": "https://gist.github.com/...",
  "trace_id": "tr_abc123"
}

primary sources

references

audit workflow

• references/v1-templates.md - V1 definitions per project type
• references/specialist-briefs.md - full specialist prompts
• references/audit-criteria.md - scoring rubrics
• references/sample-audit-output.md - complete AUDIT.md artifact
• references/conversation-examples.md - annotated ask-deep transcripts

issue enrichment (integrated from issue-context skill)

• references/issue-enrichment-templates.md - comment templates, agent prompts, decision trees
• references/diagram-generation.md - mermaid patterns for architecture visualization
• references/cli-integration.md - linear, outline, layer, git command patterns

linear integration

• references/linear-agent-patterns.md - AgentActivities and state management
• references/linear-patterns.md - Linear CLI patterns

scripts

• scripts/audit-project.sh - single project audit
• scripts/enrich-batch.sh - batch issue-context enrichment

anti-patterns