our-claude-skills/custom-skills/82-our-gdrive-organizer/shared/patterns/gotchas.md

# Gotchas

Edge cases the system has learned. When in doubt during interactive
content-based reorganization, check here first.

Each gotcha follows the format: **Pattern → Why it's tricky → Resolution**.

---

### Lesson notes for a specific lawyer/doctor/consultant

**Pattern**: `Notes – [레슨] SEO 진단 & 관리 수업 - 양제민 변호사 6회차 (대면).gdoc`
or similar lesson-format file referencing a real client by name.

**Why tricky**: Looks like training material (it IS a lesson note), but it's
client-specific (양제민 variant of 오현이혼상속센터 engagement).

**Resolution**: Belongs in `99_Project Archive/{NN_그_클라이언트}/`, NOT in
`98_Training/`. Training is for generic, reusable content. Client-specific
lesson notes are engagement records.

---

### Quote sheet with `D.intelligence Lab-` prefix and a client name

**Pattern**: `D.intelligence Lab-SEO Coaching-오현법률사무소-20240612.gsheet`

**Why tricky**: Has both a brand-rebrand candidate (`D.intelligence Lab-` →
`OurDigital-`) AND a real client name that should become `OOO`. But cell
content can't be normalized by filesystem rename.

**Resolution**:
1. Filesystem rename: `OurDigital-SEO Coaching-OOO 견적-20240612.gsheet`
2. Add to a `TODO.md` reminding the user to open the sheet in Google Sheets
   and replace `오현법률사무소` and contact info inside cells with `OOO` /
   placeholder text.
3. Move to `05_Working Template/` once both filesystem AND cell content are
   neutralized. Until then, leaving the file in place with the rename done
   is a valid intermediate state.

---

### Files at the root that look like they should be in a subfolder

**Pattern**: A top-level subfolder root contains 30+ loose files plus 0
subfolders. E.g., a `screenshots` collection directly at the top of
`98_Training/`.

**Why tricky**: The script's `MOVE_RULES` only catches very specific
patterns (`Screenshot YYYY-MM-DD…`). Manual moves often need judgment —
which subfolder should be created, what should be its name?

**Resolution**: Interactive content-based mode. Claude reads filenames in
batches, proposes a subfolder name (matching local language convention —
Korean if rest of folder is Korean), confirms with user, then moves with
`mv`. Update the parent README afterward via `our-gdrive-organize --scope index`.

---

### Korean vs English filename mixing inside one subfolder

**Pattern**: `02_SEO Audit Toolkit/` contains both English files
(`OurDigital-on-Pages Elements Kit-20250529.gsheet`) and Korean subfolders
(`참고 자료/`, `문서 양식/`).

**Why tricky**: Looks inconsistent at first glance, but is intentional —
files use English when they're "OurDigital products" and Korean when
they're "Korean-language reference materials."

**Resolution**: Don't normalize. Language tracks function:
- OurDigital-authored asset → English filename, OurDigital prefix
- External / Korean reference → Korean filename
- Subfolder for grouping Korean references → Korean folder name

---

### Empty subfolders

**Pattern**: `99_Project Archive/03_소노펠리체CC Local SEO/09_수급 정보/`
contains 0 files.

**Why tricky**: Tempting to delete to "clean up." But empty subfolders often
represent reserved engagement phases that the project just didn't reach,
or pending document deliveries.

**Resolution**: Leave empty subfolders alone unless the user explicitly
says to clean them up. They don't break anything.

---

### Numbered duplicates: `(1)`, `(2)` suffixes

**Pattern**: `D.intelligence Lab-SEO Coaching-오현법률사무소-20240612 (1).gsheet`
exists alongside the same name without the `(1)`.

**Why tricky**: Looks like a Drive sync duplicate, but `cmp` shows different
bytes — they're DIFFERENT Drive documents that happen to have the same name.

**Resolution**: `cmp` the two `.gsheet` stubs. If different (which they
usually are for `(N)`-suffixed files), preserve both with a suffix like
`(v1)`, `(v2)`, or `(legacy)`. Never overwrite blindly. If actually
identical bytes, ask user which to keep.

---

### `_unsorted/` accumulates over time

**Pattern**: After several `--scope move --apply` runs, `_unsorted/`
accumulates `.crdownload` / `.tmp` files that the user never went back to.

**Why tricky**: These are usually legitimate trash but occasionally a real
in-progress download.

**Resolution**: Don't auto-delete. Periodically prompt the user: "Your
`_unsorted/` has N files older than 30 days. Want to review?"

---

### A folder that mixes archive + active work

**Pattern**: A subfolder under `01_Active Workspaces/` contains both
ongoing work AND files from a finished engagement that should have been
archived.

**Why tricky**: Hard to tell from filenames alone. Need to check mtimes
and content (last-modified-recently → active; older + closure-marker docs →
should be archived).

**Resolution**: Interactive mode. Claude reads file mtimes + samples
content, proposes splitting into a new `99_Project Archive/{NN_client}/`
entry. User confirms before moving.

---

### D.intelligence vs OurDigital — parent company / child brand

**Pattern**: Files or folders named `D.intelligence …`, `D intelligence …`,
or with the legacy `D.intelligence Lab-` prefix.

**Why tricky**: D.intelligence is the **parent company**; OurDigital is its
**SEO-specialty child brand**. The rebrand-to-OurDigital rule only applies
when the asset is SEO-related. Non-SEO D.intelligence assets (consulting,
data, training in other practices) keep the D.intelligence name because
they belong to the parent company, not to OurDigital.

**Resolution**:
- Inside an SEO context (`02_SEO in Action/`, `00_OurDigital/04_SEO/`, or
  any folder whose name contains "SEO"): apply the standard rename
  `D.intelligence … → OurDigital …`.
- Outside SEO context: **do not rename**. Flag for user review and
  document the asset's intended owning practice.
- The `RENAME_RULES` in `code/organizer.py` cover three variants
  (`D.intelligence Lab-`, `D.intelligence`, and the no-dot `D intelligence`
  typo). The rules don't enforce the SEO-context caveat — that's the
  caller's responsibility (point the script at an SEO folder, not the
  whole Drive Stream).

---

### Brand-variant typos that escape the regex

**Pattern**: A filename uses an off-spec spelling of `D.intelligence` —
e.g., `D intelligence SEO Audit & Treatment.pdf` (no dot), or
`OurDigitial-…` (transposed letters), or `Techincal SEO` (transposed).

**Why tricky**: The standard `D\.intelligence` regex requires the literal
dot, so the no-dot variant slips through. Same for OurDigital typos —
they don't match the brand pattern at all and look like normal filenames.

**Resolution**:
1. When you find one during a manual review, do the rename via `mv` and
   immediately consider whether to add a regex variant to `RENAME_RULES`.
2. The current rules cover: `D.intelligence Lab-`, `D.intelligence`, and
   `D intelligence` (no-dot, word-boundaries to avoid false positives).
3. Common typos that are NOT in regex (because they're one-off mistakes):
   `OurDigitial`, `Techincal`. Catch with `mv` during manual review.

---

### Real client names in `예시 자료 모음/`

**Pattern**: Files in `02_…/예시 자료 모음/` that still have real client
names in the filename — e.g., `OurDigital-SEO Audit-1gada.com-20240703.xlsx`,
`OurDigital-Sono International-Preliminary SEO Audit-20240927.gdoc`.

**Why tricky**: The folder's canonical role is "neutralized example
deliverables" — examples to show in pre-sales without exposing real client
data. A file with a real client name in this folder is a half-done
neutralization. The original engagement copy usually exists elsewhere
(`99_Project Archive/{NN_client}/` or `04_Case Studies/`).

**Resolution**:
1. Filesystem rename to neutralize the FILENAME using `OOO`-style
   placeholders: `OurDigital-OOO 호텔 체인-Preliminary SEO Audit-…gdoc`.
2. Add to a `TODO.md` reminding the user to also neutralize CELL CONTENT
   (real names, contact info, URLs, keyword examples) inside the source
   Sheet/Doc — filesystem rename doesn't touch cell content.
3. Don't delete the file even though the original exists elsewhere — the
   neutralized example serves a different purpose (sales / training) than
   the archived original (engagement record).
4. If the original doesn't exist elsewhere, copy it to the right archive
   folder FIRST before neutralizing the example.

---

### Near-duplicate templates across `문서 양식/` and `05_Working Template/`

**Pattern**: Same template name in both
`02_…/문서 양식/OurDigital-SEO Audit Template-{date1}.gsheet` and
`05_Working Template/OurDigital-SEO Audit Template-{date2}.gsheet` with
different dates (and different Doc IDs).

**Why tricky**: Looks like the same template at v1 and v2 (good cleanup
target — keep the newer, archive the older). But sometimes they're
genuinely different templates that just happen to share a name.

**Resolution**:
1. `cmp` the .gsheet stubs first. Always different (different Doc IDs)
   for files at different dates — that just confirms they're separate
   Drive Docs, not bytes-identical stubs.
2. The Doc IDs alone can't tell you whether the cell content is similar.
   Open both Sheets in Google Drive. Usually one is a direct refinement
   of the other (older = v1, newer = v2 with added rows/columns).
3. If clearly v1 / v2 of same template: delete v1, OR move v1 to
   `05_Working Template/` with `(legacy v1)` suffix.
4. If genuinely different (e.g., one is "quick check" and other is
   "comprehensive"): rename to disambiguate explicitly.
5. Always defer to the user for the open-and-compare step. Add to
   `TODO.md` with both Doc IDs + paths so the user knows what to compare.

---

### Stray screenshot that turns out to be a process diagram

**Pattern**: A `Screenshot_YYYY-MM-DD…png` in a folder of templates that
the script's `MOVE_RULES` would normally route to a `screenshots/` subdir.

**Why tricky**: The MOVE_RULES regex (`^Screenshot \d{4}-\d{2}-\d{2}…`)
treats anything with that prefix as junk to be tucked away. But sometimes
the screenshot is actually a captured workflow diagram, org chart, or
reference visualization that has real value AND a meaningful home elsewhere.

**Resolution**:
- Always view the screenshot before moving it (use `Read` on the .png).
- If it's a diagram / reference visualization: rename to a descriptive
  filename and move to the most relevant subfolder (often `참고 자료/`
  for audit-toolkit context, `docs/` for code-related).
- If it's an actual junk screenshot (UI snapshot during work): apply the
  default rule and move to `screenshots/`.
- The MOVE_RULES regex pattern uses the macOS default
  `Screenshot YYYY-MM-DD at HH.MM.SS AM/PM.png` (with spaces). The
  underscore variant `Screenshot_YYYY-MM-DD_at_*` does NOT match —
  catch those manually during content review.

---

### `D_intelligence` (underscore) — typo, NOT a regex variant

**Pattern**: A file uses `D_intelligence` with an underscore separator
between `D` and `intelligence` instead of a dot. E.g.,
`D_intelligence_홍아현_프로젝트부속계약서_20260501.gdoc`.

**Why tricky**: It LOOKS like a third regex-escaping variant of the brand
prefix (alongside `D.intelligence` with dot and `D intelligence` with
space, both of which ARE valid spellings the parent company uses). But
underscore is **wrong** — D.intelligence is always written with a dot.
The underscore form is purely an accidental typo (probably auto-generated
by a system that sanitized dots to underscores).

**Resolution**:
1. Treat as a one-off typo fix: rename `D_intelligence` → `D.intelligence`
   via `mv`. The rest of the filename keeps its underscores (those are
   legitimate field separators in the file's own naming scheme).
2. **Do NOT add to `RENAME_RULES`.** Adding a `D_intelligence` regex
   would cause false positives in any filename that uses underscores as
   field separators between something ending in `D` and something starting
   with `intelligence` — unlikely but defensively avoid widening the rules.
3. Same applies to other one-off accidental variants: fix with `mv`,
   document the fix here, but don't widen the rules.

---

### Externally-generated filenames vs OurDigital convention

**Pattern**: Files in an active client workspace whose names come from
external systems and don't follow OurDigital convention. E.g.:
- `Jamie_Naver_Booking_Products_v1.0.gsheet` (Title_Case_With_Underscores
  — looks like a Google Sheets name template)
- `jam_medical_advertising_review_guide_20251119154552.gslides`
  (lowercase + 14-digit timestamp — looks like an export from a
  publishing tool)
- `jamie_monthly_sow_standard.docx` (lowercase + underscores — looks
  like a Word template name)

**Why tricky**: These names are functional and the user might prefer to
preserve them as-is to maintain traceability with the originating system.
But they violate the canonical `{ClientPrefix}-{topic}-{date}.{ext}`
pattern from `canonical-files.md`, which makes the folder feel
inconsistent.

**Resolution**:
- The OurDigital convention wins inside `01_Active Workspaces/{NN_client}/`
  because the user owns that folder's organization. Normalize:
  - `Jamie_` → `JAM-`
  - `jamie_` → `JAM-`
  - `jam_` → `JAM-`
  - `_` field separators → `-` (or space inside hyphenated phrases)
  - Long timestamps `YYYYMMDDhhmmss` → `YYYYMMDD` (drop time portion)
  - Title_Case_Words → Title Case Words (use spaces inside hyphen-separated phrases)
- Default to normalizing unless the user says preserve. The originating
  system can usually re-export with a new name if needed.
- If the file is truly the system's source-of-truth filename (e.g., a
  webhook expects an exact filename match), keep it and note WHY in a
  README inside the same folder.

---

### Reference library naming inconsistency (do NOT normalize)

**Pattern**: A reference folder like `90_Brand Management Reference/`
contains 20+ image files imported as a batch from various sources, with
mixed naming conventions (Title_Case, lowercase-hyphens, Korean-spaces,
auto-generated junk).

**Why tricky**: It's tempting to normalize all the names for consistency.
But the inconsistency reflects the varied **sources** of the references —
each filename traces back to its origin (Slideshare slug, vendor
whitepaper, screenshot of a textbook page, Korean blog).

**Resolution**:
- **Do not bulk-rename reference filenames** for cosmetic consistency.
  They have provenance value as-is.
- DO fix individual filenames that are functionally broken:
  - Double extensions (`foo.png--example.png` → `foo-example.png`)
  - Filesystem-illegal characters
  - Truncated names that lost the meaning
- DO group by topic into subfolders if the count exceeds ~15 files at the
  root: `frameworks/`, `examples/`, `ko/` (or whatever fits the content).
  Subfolders provide structure without touching the legitimate filename
  diversity.

---

## Adding new gotchas

When you (Claude) encounter a new ambiguous case during a content-based
reorganization session, add an entry here BEFORE moving on. Format:

```
### Short pattern title

**Pattern**: filename / structure example.

**Why tricky**: what makes this hard.

**Resolution**: what to do.

---
```

This is how the system gets smarter over time. The patterns library is
the institutional memory.