rtk-ai/rtk

enhancement: document all filtering behaviors and data loss per command

Open

#1163 opened on Apr 10, 2026

View on GitHub
 (2 comments) (1 reaction) (0 assignees)Rust (48,085 stars) (2,914 forks)batch import
documentationeffort-mediumgood first issue

Description

Problem

RTK's README and docs describe the token savings benefits but do not clearly document what data is lost or transformed for each command. Users and AI agents need to understand the trade-offs before enabling the hook.

Missing documentation

For each supported command, users should know:

Command What RTK does What is lost
`rtk curl` JSON->schema, 30-line truncation Actual API response values
`rtk grep` 80 char line limit, 200 result cap Long matches, results beyond 200
`rtk ls` Tree view, grouped by directory Permissions, sizes, dates, symlinks
`rtk git diff` Changed lines only Context lines, hunk headers (partially fixed in #1009)
`rtk git log` One-line commits Full commit messages, diffs
`rtk cat/read` Signature extraction, line limits File body content (in aggressive mode)
`rtk cargo test` Failures only Passing test names, warnings
`rtk env` Masks sensitive values Actual environment variable values

Impact

  1. Users cannot make informed decisions about which commands to exclude
  2. AI agents cannot reason about when to use rtk proxy vs rtk commands
  3. Debugging is harder when users do not realize output is filtered

Proposed solution

Create a new doc: `docs/FILTERING_BEHAVIOR.md` that documents:

  1. Per-command filtering behavior: What each command filter does
  2. Data loss matrix: What information is removed or transformed
  3. Workarounds: How to get raw output for each command
  4. Recommended excludes: Which commands to exclude based on use case

Acceptance criteria

  • New documentation file exists at docs/FILTERING_BEHAVIOR.md
  • Each supported command has a documented filtering behavior
  • Data loss is clearly described
  • Workarounds (exclude_commands, --raw, proxy) are documented

Contributor guide

Tech stack
rust
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Basic understanding of RTKMarkdown writing skills
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
80
Research direction
Review the source code for each command in the src/commands/ directory to confirm the exact filtering behavior. Create a new file docs/FILTERING BEHAVIOR.md following the template in the issue. Ensure all commands mentioned in the issue are covered, and add any additional commands if found. Reference the existing README for consistency.