pilastdigit/trip-workflow/trip-compact

ARCHI Compaction Mode

You are now in compaction mode - intelligently reducing ARCHI.md size while preserving its value.

Why Compact?

ARCHI.md should not exceed _~20k tokens_. A bloated ARCHI:

• Consumes tokens that could be used for actual work
• Slows down every command that reads it
• May contain redundant or outdated information
• Defeats the purpose of "balanced detail vs token usage"

Your Task

Compact: @docs/ARCHI.md

If `$ARGUMENTS` contains `--sync`: run only the Sync Audit below, then stop. Otherwise run the Sync Audit first (a stale claim is bloat too), then Steps 1–6.

Sync Audit: ARCHI vs codebase

ARCHI.md is only useful while it is true. TRIP-3 verifies the sections each release touches; this audit covers the whole document and catches what accumulated in between.

Method — one section (##) at a time, cheapest check that settles each claim:

1. List the section's concrete claims: paths, commands, routes, tables and columns, env vars, named flow steps. Skip prose about intent or rationale — it cannot drift.
2. Verify each with ls, grep -n, or a manifest lookup (package.json scripts, Cargo.toml, CMake targets…). Read a source file only when a claim describes a flow and a grep cannot settle it. Never read a file to confirm something ls already answered.
3. Record every mismatch as: section · claim · reality · proposed fix. Missing coverage counts too: a top-level directory or route module present in the tree but absent from ARCHI.

Report the table (or "no drift found"), then use the `AskUserQuestion` tool:

• Question: "ARCHI drift audit: [N] claims checked, [M] stale, [K] gaps. Apply the proposed fixes?"
• Options: "Apply all" (edit ARCHI.md, following docs/ARCHI-rules.md), "Let me pick" (user lists the rows to apply), "Report only" (stop here)

In --sync mode, stop after applying. Otherwise continue to Step 1 with the corrected file.

Step 1: Assess Current State

First, measure the actual token count using the bundled script:

bash .claude/skills/TRIP-compact/count-tokens.sh docs/ARCHI.md

Then read the full ARCHI.md and evaluate:

1. Identify bloat sources:

• Verbose explanations where concise would suffice
• Redundant information repeated across sections
• Implementation details that belong in code comments, not architecture docs
• Overly detailed file listings
• Excessive examples

If token count > 20,000, report the assessment to the user, then use the `AskUserQuestion` tool:

• Question: "ARCHI.md is at ~[X] tokens (target: ~10,000-15,000). Main bloat sources: [list top 3-5]. Proceed with compaction?"
• Options: "Yes, compact" (proceed with compaction strategies), "No, leave as-is" (stop here)

If token count <= 20,000, report to the user, then use the `AskUserQuestion` tool:

• Question: "ARCHI.md is at ~[X] tokens — within acceptable range. Would you still like to compact it further?"
• Options: "Yes, compact anyway" (proceed with compaction), "No, it's fine" (stop here)

If "No" in either case, stop here.

Step 2: Compaction Strategies

Apply these strategies in order of priority:

2.1 Remove Redundancy (First Pass)

• Eliminate repeated information across sections
• Consolidate overlapping descriptions
• Remove "see above" or "as mentioned" patterns - restructure instead

2.2 Increase Information Density

Transform verbose patterns into dense ones:

Before (verbose):

## Authentication System
 
The authentication system in this project uses Supabase for managing user
authentication. When a user logs in, the system calls the Supabase auth API
to verify their credentials. After successful authentication, a session is
created and stored. The session token is then used for subsequent API calls
to authenticate the user. We also support role-based access control where
users can have either an ADMIN role or a USER role, which determines what
actions they can perform in the application.

After (dense):

## Authentication
 
**Provider**: Supabase Auth
**Flow**: Login → Supabase API → Session created → Token for subsequent calls
**RBAC**: `ADMIN` (full access) | `USER` (read-only library, settings)

2.3 Convert Prose to Structured Formats

• Use tables instead of paragraphs for comparisons
• Use bullet points instead of sentences
• Use code for paths, commands, types
• Use diagrams (mermaid) to replace lengthy flow descriptions

2.4 Collapse Implementation Details

Keep: What and Why Remove: How (implementation specifics)

Before:

The useTranscription hook manages the transcription state by using useState
for the segments array, useEffect to fetch data when videoId changes, and
useCallback for memoized handlers. It also implements error boundaries...

After:

`useTranscription`: Orchestrates transcription data fetching and state management

2.5 Summarize File Listings

Before:

-`src/components/auth/LoginForm.tsx` - Login form component
-`src/components/auth/LogoutButton.tsx` - Logout button component
-`src/components/auth/RegisterForm.tsx` - Registration form component
-`src/components/auth/ForgotPassword.tsx` - Password reset component
-`src/components/auth/AuthProvider.tsx` - Auth context provider

After:

-`src/components/auth/` - Auth UI components (Login, Logout, Register, ForgotPassword, AuthProvider)

2.6 Use References Instead of Duplication

Instead of explaining the same pattern in multiple places:

See [Pattern Name](#pattern-name) for details.

Step 3: Preserve Critical Information

NEVER compress or remove:

• Project overview and purpose
• Technology stack with versions
• Directory structure (can be summarized but not removed)
• Core architectural principles
• Key patterns and their locations
• Data flow diagrams
• API contracts/interfaces
• Configuration requirements
• Build/deployment commands

These are the backbone - compress everything else first.

Step 4: Validate Compression

After compaction, verify:

• [ ] All major sections still present
• [ ] Technology stack complete
• [ ] Directory structure understandable
• [ ] Key patterns still documented
• [ ] No broken internal links
• [ ] Mermaid diagrams still valid
• [ ] New developer could still onboard with this doc

Step 5: Measure & Present Changes

Run the script again on the compacted file:

bash .claude/skills/TRIP-compact/count-tokens.sh docs/ARCHI.md

Present the compaction results to the user, then use the `AskUserQuestion` tool:

• Question: "Compaction complete: ~[X] → ~[Y] tokens ([Z]% reduction). Changes: [brief summary]. How does the compacted ARCHI.md look?"
• Options: "Looks good" (compaction is complete), "Restore some detail" (specific sections need more detail), "Too aggressive" (undo and try lighter compaction)

Step 6: Iterate if Needed

If user identifies sections that need more detail:

• Restore specific details for those sections
• Compensate by further compressing less critical sections

If still over 15k tokens after smart compression:

• Consider splitting into ARCHI.md (core) + ARCHI-detailed.md (deep dives)
• Only the core file is read by default

Compaction Principles

1. Density over length - Same information, fewer words
2. Structure over prose - Tables, bullets, code blocks
3. References over repetition - Link, don't duplicate
4. What/Why over How - Architecture, not implementation
5. Current over historical - Remove obsolete content
6. Essential over comprehensive - 80/20 rule applies

When to Run This Skill

• --sync every few months, or the first time the agent guesses a path that ARCHI.md describes wrongly
• ARCHI.md feels sluggish to read
• You notice redundant information
• Periodically (every few months) as maintenance
• When token usage becomes a concern