Reclassification

Reclassification

Critically evaluate an existing classification system and produce an improved version. Applies to any domain where items are grouped into categories: code modules, document folders, data labels, skill libraries, config buckets, or structured datasets.

When to Use

• A classification system has grown organically and feels inconsistent
• Categories overlap, are too broad, or are too granular
• New items don't fit cleanly into existing groups
• Downstream consumers (users, pipelines, agents) struggle with current groupings
• You need to audit whether a taxonomy still serves its original purpose
• Merging two classification systems after a team or project merge
• Preparing data for a migration where clean categories matter
• Evaluating whether skills, tools, or documents should be consolidated or split

---

Core Principles

1. Understand before changing — Reconstruct the reasoning behind the current classification before proposing changes. Every existing grouping had a reason, even if that reason is no longer valid.
2. Classify for the consumer — Optimize groupings for the downstream use case (discoverability, routing, filtering, agent selection), not for the author's mental model.
3. Mutual exclusivity — Each item should belong to exactly one category. If an item fits two categories equally well, the boundaries are wrong.
4. Collectively exhaustive — Every item must have a home. If orphans exist, the taxonomy has gaps.
5. Right-sized groups — Categories that are too large lose signal; categories that are too small add navigation cost. Aim for balance within stated constraints.
6. Names carry meaning — A category name should let someone predict its contents without reading a description. Rename when the name misleads.
7. Stable under growth — A good taxonomy accommodates new items without restructuring. If every new addition requires a new category, the scheme is too rigid.

---

Inputs

Gather these before starting. Not all are required — work with what's available.

| Input | Required | Description | |-------|----------|-------------| | Items | Yes | The things being classified (files, rows, labels, skills, endpoints, etc.) | | Current classifications | Yes | How items are currently grouped (folder structure, labels, column values, tags) | | Downstream use cases | Recommended | Who consumes these classifications and for what purpose | | Min category size | Optional | Minimum number of items per category (default: 2) | | Max category size | Optional | Maximum number of items per category (default: no limit) | | Split threshold | Optional | When a category exceeds this size or has clear sub-clusters, consider splitting | | Merge threshold | Optional | When two categories have fewer than this many items each and overlap, consider merging | | Constraints | Optional | Fixed categories that cannot be renamed/removed, naming conventions, external dependencies |

---

Process

Step 1: Inventory the Current State

List every item and its current classification. For large datasets, summarize with counts.

## Current Classification Inventory

| Category | Count | Sample Items |
|----------|-------|-------------|
|  |  | , ,  |
|  |  | ,  |
| ... | ... | ... |

**Total items**: 
**Total categories**: 
**Uncategorized items**: 

Step 2: Reconstruct the Classification Logic

Before critiquing, understand the system:

• What was the likely organizing principle? (by function, by audience, by lifecycle stage, by domain, alphabetical, chronological)
• What use case was it designed for? (navigation, search, routing, reporting, access control)
• When was it created? Has the scope of items changed significantly since then?
• Who classified the items? One person's mental model or a team convention?
• Is there a logic at all? Many classifications are accidental — items added over time with no governing principle. This is a valid finding.

Document this as:

## Classification Logic (Reconstructed)

**Organizing principle**: 
**Original use case**: 
**Classifier**: 
**Scope drift**: 
**Coherence**: 

If no coherent logic exists, note that explicitly. An accidental classification is the strongest signal that reclassification will add value.

Step 3: Evaluate Each Category

For every category, answer these questions:

| Question | What you're checking | |----------|---------------------| | Is the name accurate? | Does the name describe what's actually inside? | | Is it internally coherent? | Do all items share a clear, common trait? | | Is it distinct from neighbors? | Could items be confused with another category? | | Is it right-sized? | Too few items ( split threshold)? | | Does it serve the downstream use case? | Would a consumer find what they need here? |

Quantitative signals — When working with structured data (CSV, JSON, database rows) or large item sets (50+), compute these before relying on qualitative judgment:

• Distribution: Item count per category. Flag categories with split_threshold.
• Overlap rate: How many items could plausibly fit in two or more categories? High overlap (>20%) signals boundary problems.
• Orphan rate: How many items are uncategorized or in a catch-all? High orphan rate signals taxonomy gaps.
• Name–content alignment: For text items, check whether the category name appears in or relates to the item content.

Produce a diagnostic table:

## Category Evaluation

| Category | Accurate Name? | Coherent? | Distinct? | Size | Serves Use Case? | Issue |
|----------|---------------|-----------|-----------|------|-------------------|-------|
|  | ✅ | ✅ | ⚠️ overlaps with  | 12 | ✅ | Boundary issue |
|  | ❌ name misleads | ✅ | ✅ | 3 | ⚠️ | Rename candidate |
|  | ✅ | ❌ mixed concerns | ⚠️ | 18 | ❌ | Split candidate |
| ... | ... | ... | ... | ... | ... | ... |

Step 4: Identify Reclassification Actions

Based on the evaluation, propose specific actions. Each action must have a rationale tied to a principle or downstream use case.

Action Types

| Action | When to Apply | Template | |--------|--------------|----------| | Merge | Two categories overlap significantly or are both undersized | Merge ` + → because | | **Split** | A category contains distinct sub-clusters or exceeds the split threshold | Split → + because | | **Rename** | The name doesn't match the contents or is ambiguous to consumers | Rename → because | | **Redistribute** | Individual items are miscategorized | Move from to because | | **Create** | Orphaned items share a trait that deserves its own category | Create for , because | | **Dissolve** | A category adds no signal — its items fit better elsewhere | Dissolve , redistribute items to , because | | **Keep** | The category is well-formed and serves its purpose | Keep ` as-is |

## Proposed Actions

| # | Action | Detail | Rationale |
|---|--------|--------|-----------|
| 1 | Merge | `planning` + `roadmap-planning` → `planning` | 80% content overlap; consumers can't distinguish them |
| 2 | Split | `comms` → `internal-comms` + `external-comms` | Distinct audiences with different voice rules |
| 3 | Rename | `general-coding` → `project-setup` | Contents are scaffolding conventions, not general coding |
| 4 | Keep | `security` | Well-scoped, distinct, right-sized |

Step 5: Propose the New Classification

Present the full reclassified structure side by side with the original.

## Proposed Classification

| New Category | Items | Source (Original Category) |
|-------------|-------|---------------------------|
|  | ,  | was  |
|  | , ,  | split from  |
| ... | ... | ... |

**Total items**:  (should match original)
**Total categories**:  (was )

Step 6: Validate the Proposal

Run these checks before finalizing:

| Check | Pass? | |-------|-------| | Every item from the original inventory appears exactly once | | | No category is below the minimum size threshold | | | No category is above the maximum size threshold (if set) | | | Every category name is unambiguous to the downstream consumer | | | The taxonomy is stable — a plausible new item would fit without restructuring | | | The number of actions is proportional to the problems found (don't over-reorganize) | |

Step 7: Iterate if Needed

Reclassification is rarely one-pass. Before finalizing:

• Present the proposal to stakeholders (or re-read it yourself after a break). Fresh eyes catch category names that feel obvious to the author but confuse consumers.
• Test with new items: Take 3–5 items that don't exist yet (or were recently added) and try to classify them under the proposed scheme. If placement is ambiguous, the boundaries need work.
• Adjust and re-validate: Loop back to Step 6 after changes. Don't skip validation on the revised version.

Step 8: Present the Migration Path

If the reclassification will be implemented (not just theoretical), outline the steps:

## Migration Path

1. 
2. 
3. 
4. 

**Breaking changes**: 
**Rollback**: 

---

Output Format

Every reclassification analysis should produce these sections:

1. Current Classification Inventory — What exists today, with counts
2. Classification Logic — Reconstructed rationale for the original scheme
3. Category Evaluation — Per-category diagnostic table (with quantitative signals for large datasets)
4. Proposed Actions — Specific merge/split/rename/redistribute/create/dissolve actions with rationale
5. Proposed Classification — The full new structure with item mapping
6. Validation Checklist — Confirm the proposal is sound
7. Iteration — Test with new items, gather feedback, adjust
8. Migration Path — Steps to implement (if applicable)

---

Tuning Parameters

These defaults can be overridden by the user:

| Parameter | Default | Effect | |-----------|---------|--------| | min_category_size | 2 | Categories below this trigger a merge review | | max_category_size | none | Categories above this trigger a split review | | split_threshold | 15 | Suggest splitting when a category exceeds this count | | merge_threshold | 3 | Suggest merging when two related categories are each below this count | | rename_confidence | high | Only rename when the mismatch between name and contents is clear | | preserve_list | [] | Category names that must not be changed (external dependencies) |

---

Flat vs. Hierarchical

Not every classification needs to be flat. Consider hierarchy when:

| Signal | Recommendation | |--------|---------------| | 20 categories with natural parent groups | Add one level — group related categories under parents | | Items have a clear primary axis + secondary axis | Use hierarchy for primary, tags for secondary | | Consumers navigate top-down (browse) | Hierarchy helps | | Consumers search or filter (query) | Flat + tags is often better |

Never go deeper than two levels. If you need three, the top level is too granular.

---

Applying to Structured Data (CSV, JSON, Database)

When reclassifying a column in a dataset rather than a folder structure:

1. Inventory = SELECT category, COUNT(*) FROM data GROUP BY category ORDER BY COUNT(*) DESC
2. Evaluate = Look at value distribution, null rates, and sample rows per category
3. Actions = Express as a mapping table: old_value → new_value
4. Validate = Run the mapping and verify counts match, no NULLs introduced, downstream queries still work
5. Migrate = Provide the SQL UPDATE or Python/pandas transformation, not just the conceptual mapping

## Value Mapping

| Old Value | New Value | Count | Rationale |
|-----------|-----------|-------|-----------|
| "bug" | "defect" | 142 | Align with established terminology |
| "enhancement" | "feature" | 89 | Merge: distinction wasn't meaningful for reporting |
| "task" | "task" | 204 | Keep as-is |
| "question" | → dissolve | 12 | Redistribute: 8 are actually bugs, 4 are feature requests |

---

Anti-Patterns

| Anti-Pattern | Why It Fails | |-------------|-------------| | Reclassify everything | Massive reorganizations break references and confuse users. Change only what's broken. | | Classify by implementation | Grouping by technology instead of user need creates categories that don't help consumers. | | One item per category | Hyper-granular taxonomies add navigation cost without adding signal. | | Catch-all categories | "Other" or "Misc" categories are where items go to die. If items don't fit, the taxonomy has gaps. | | Rename without redirects | Renaming breaks links, configs, and muscle memory. Always provide a migration path. | | Optimize for the author | The author's mental model is not the consumer's. Classify for retrieval, not for filing. | | Skip the inventory | Proposing changes without counting what exists leads to misjudged merges and splits. |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: michaelsvanbeek
• Source: michaelsvanbeek/personal-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.