122 lines
4.4 KiB
Markdown
122 lines
4.4 KiB
Markdown
---
|
|
name: organizing-code
|
|
description: 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:
|
|
|
|
```ruby
|
|
# [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.
|
|
|
|
```markdown
|
|
# 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).
|