chatwoot-develop/skills/organizing-code/SKILL.md

name	description
organizing-code	Organizes and clarifies codebase structure after auditing. Focuses on readability, standardized comments, and non-destructive cleanup without altering behavior.

Code Organization & Clarification Specialist

Mission

To reduce confusion and cognitive load by organizing code, standardizing comments, and clarifying intent, WITHOUT deleting files, changing behavior, or breaking contracts. This skill acts as a "gardener" for the codebase, prioritizing idempotency and reversibility.

When to use this skill

• AFTER running the auditing-code skill.
• When the codebase feels cluttered or ambiguous.
• To prepare legacy code for future refactoring or AI analysis.
• Trigger phases: ORGANIZE, CLARIFY, DOCUMENT, TIDY.

Workflow

Copy this checklist to task.md:

• Phase 1: Input Analysis
  • Read audit_report.md (if available).
  • Identify areas marked as "CAUTION" or "KEEP".
• Phase 2: Check Idempotency (Content-Based)
  • Verify if files already meet the organization standards.
  • Skip files that already have sorted imports or standard headers.
  • Rule: Logic must be deterministic based on FILE CONTENT, ignoring git history.
• Phase 3: Safe Cleanup (Non-Destructive)
  • Remove unused local variables (verified SAFE).
  • Organize imports (sort, group, remove dups - strict side-effect check).
  • Standardize comments.
• Phase 4: Clarification & Documentation
  • Add standard tags ([INTENTIONAL], [LEGACY]).
  • Document implicit dependencies (Gemfile or docs).
• Phase 5: Reporting
  • Generate organization_report.md.

Instructions

1. Idempotency Rules (Crucial)

Before applying any change, check if it's needed based on FILE CONTENT:

• Comments: Do NOT add [INTENTIONAL] if the line already has it.
• Imports: Check if imports are already sorted. If yes, skip.
• Logic: If the code is already clear, DO NOT touch it.

2. Actions & Safety

Imports & Formatting

• Global Formatting: PROHIBITED. Do not run Prettier/ESLint on the whole file.
• Local Adjustments: Minimal whitespace changes are allowed ONLY within the organized lines (e.g., grouping imports).
• Justification: Any formatting tweak must be explicitly logged in the organization report.

Dependencies

• Ruby (Gemfile): Use # comments for legacy/audit notes.
• JS (package.json): NO COMMENTS inside JSON (strict format).
  • Action: Create or update docs/dependency_notes.md.
  • Content: Reference the package name, version, and reason for the note.

Structural Integrity (Strict No-Touch)

• NO moving files between folders.
• NO rearranging domain boundaries.
• NO altering namespaces or explicit exports.

3. Placeholder Strategy

For code that appears unused but is blocked from deletion:

DO NOT DELETE. Instead, wrap or annotate:

# [INTENTIONAL] Reserved for future feature expansion (Phase 2)
def future_method
  # ...
end

Standard Tags:

• [INTENTIONAL] - Kept on purpose.
• [LEGACY] - Old behavior, do not touch.
• [FUTURE] - Planned features.

4. Report Format

Output to organization_report.md with explicit reasoning. Ensure columns are consistent.

# Organization Report: [Scope]

## Changes Applied

| File         | Change             | Reason              | Risk | Scope       |
| :----------- | :----------------- | :------------------ | :--- | :---------- |
| `User.rb`    | Sorted imports     | Readability         | Low  | Local       |
| `Billing.rb` | Added [LEGACY] tag | Identified in Audit | None | Methodology |

## Skipped / Preserved

| File           | Item        | Reason                         | Risk   | Scope       |
| :------------- | :---------- | :----------------------------- | :----- | :---------- |
| `Init.js`      | Import Sort | Potential side-effect import   | Medium | Integration |
| `package.json` | Comments    | JSON does not support comments | Low    | Config      |

## Structural Suggestions (For Future)

- Consider moving `Admin` module to its own namespace (documented only).

Anti-Patterns

• Moving code "to look prettier" or aesthetic reordering.
• Touching entrypoints (Jobs, Webhooks, AI Agents).
• Redundant tagging (Adding [INTENTIONAL] twice).
• Global Reformatting (Changing whitespace outside of target lines).