feedback
Evaluate TLDR command outputs against quality criteria and log results for improvement tracking. This is a development tool for improving the /tldr skill itself.
Path Resolution
All evaluation data lives inside the TLDR plugin directory. This skill is at skills/feedback/SKILL.md — the plugin root is two directories up (the directory containing skills/, docs/, and .claude-plugin/). All file paths below are relative to the plugin root.
- Scoring rubrics:
skills/feedback/references/EVALUATION.md - Evaluation log:
docs/evaluation/evaluation-log.md - Sample files:
docs/evaluation/samples/NNN-description.md - Notes catalog:
docs/evaluation/notes.md
Evaluation Workflow
Step 1: Identify the Sample
Determine the input mode:
- Interactive (default): User pastes or references an original message and its TLDR output
- Automated (
--no-user-score): Called from/tldr:note --ex— skip user prompts, agent scores only
Step 2: Load Scoring Rubrics
Read references/EVALUATION.md (bundled with this skill) for the complete scoring criteria, detailed rubrics for each dimension, and the sample file format template.
Step 3: Determine Next Sample ID
Read docs/evaluation/evaluation-log.md and find the highest existing sample ID. The new sample is that number + 1, zero-padded to 3 digits (e.g., 004).
Step 4: Score the Sample
Evaluate on four criteria (Completeness, Conciseness, Actionability, Accuracy) at 2.5 points each — detailed rubrics are in references/EVALUATION.md.
For each criterion, produce: (1) items captured correctly, (2) items missed or needing improvement, (3) a numeric score with one-line justification.
Step 5: Provide Analysis
Include in the evaluation:
- What Went Well — Specific strengths
- What Needs Work — Specific weaknesses
- Recommendations — Actionable improvements for future TLDR versions
Step 6: Create Sample File
Write to docs/evaluation/samples/NNN-description.md following the format template in references/EVALUATION.md:
- Header with date, type, context
- Original message (or URL reference if external)
- TLDR output
- Claude's evaluation with breakdown
- User's evaluation section (populated or "Not provided")
Step 7: Update Evaluation Log
Update docs/evaluation/evaluation-log.md:
- Increment "Samples Collected" count
- Recalculate all averages (overall + per-criterion)
- Add row to the evaluation samples table
- Update "Samples with User Feedback" count if user scored
Step 8: User Score Handling
Interactive mode (default):
- Present the agent's score and analysis
- Ask the user for their score (0.0-10.0) and optional feedback
- If user provides a score, update the sample file and evaluation log
Automated mode (--no-user-score):
- Skip user prompts entirely
- Mark sample status as "Unscored" in the log
- Set user evaluation to "Not provided" / "None"
Output
After logging, provide a brief summary in chat:
Sample 004 logged (8.5 / 10.0)
- Strengths: Captured all key findings and file paths accurately
- Needs work: Two bullets could be more action-oriented
- Running tally: 4 samples, 9.1 avg, 1 with user feedback
Saved to docs/evaluation/samples/004-auth-refactor.md
Converted and distributed by TomeVault — claim your Tome and manage your conversions.