Verify Directory Structure — Parallel Audit with Shell Property Checks

This skill provides a systematic approach to diagnosing file access issues and auditing source trees efficiently. It extends the parallel batch reading approach with an integrated shell property check phase that combines

head -N

and

wc -l

into a single

run_shell

call, co-scheduled with directory listing in Phase 1. This eliminates a common extra iteration that would otherwise be required to check file properties such as line counts and leading content (e.g., CSS/config file headers).

---

Steps

Phase 1 — Directory Verification + Shell Property Checks (Combined)

Key optimization: Fire

list_dir

calls and

run_shell

property checks in the same iteration. This avoids a dedicated iteration later just to learn "how many lines does this file have?" or "what is the first line of this CSS file?".

1. Identify Target Paths: Collect every file or directory path involved in the operation. Prefer absolute paths to eliminate ambiguity. At this stage, also note any files whose properties (line count, header content) you already know you will need — typically CSS, config, or data files.

2. Issue Parallel

   list_dir

   +

   run_shell

   Calls Simultaneously:
   • Call

     list_dir

     on each relevant directory.
   • In the same iteration, issue one or more

     run_shell

     calls that bundle

     head

     and

     wc -l

     for known target files using a single compound shell command.

   Iteration 1 (parallel):
     list_dir(src/components)
     list_dir(src/styles)
     run_shell("head -5 src/styles/main.css && echo '---' && wc -l src/styles/main.css")
     run_shell("head -3 vite.config.ts && echo '---' && wc -l src/main.ts")
   

   Compound shell pattern (combine head + wc + any other checks for a file):

   # Single run_shell call — multiple files, multiple checks, zero extra iterations
   head -10 path/to/file.css && echo "LINE_COUNT:" && wc -l path/to/file.css && \
   echo "---" && head -5 path/to/config.ts && echo "LINE_COUNT:" && wc -l path/to/config.ts
   

3. Verify Existence & Permissions: Confirm directories exist and that the current user has read (and, if needed, write/execute) permissions. If a directory is missing, create it before proceeding (

   mkdir -p

   ). If permissions are insufficient, adjust them before retrying.

4. Build a File Manifest: From the

   list_dir

   output, compile the complete list of files to be audited. Group them logically (e.g., by subdirectory or file type) so they can be read in parallel batches in Phase 2.

5. Record Shell Check Results: Parse and store the

   head

   /

   wc -l

   output alongside the manifest. This data is immediately available for the final audit report without any additional iterations.

---

Phase 2 — Parallel Batch File Reading

Why this matters: Reading files sequentially costs one iteration per file. Reading them in parallel batches collapses N files into ⌈N/batch_size⌉ iterations — a significant speedup when auditing dozens of files.

6. Determine Batch Size: Default to reading 5–10 files per batch. Reduce the batch size if individual files are very large; increase it for small config/index files. Files whose content was partially previewed via

   head

   in Phase 1 should still be fully read here if their complete content is needed.

7. Issue Parallel

   read_file

   Calls: Within each batch, invoke

   read_file

   for all files simultaneously (a single iteration). Do not wait for one file before requesting the next within the same batch.

   Batch 1 (parallel): read_file(src/components/A.tsx)
                        read_file(src/components/B.tsx)
                        read_file(src/components/C.tsx)
                        read_file(src/components/D.tsx)
                        read_file(src/components/E.tsx)
   
   Batch 2 (parallel): read_file(src/components/F.tsx)
                        ...
   

8. Collect & Triage Results: After each batch completes, scan results for errors (file-not-found, permission denied) and flag them immediately. Do not abort the remaining batches; continue and aggregate all findings.

9. Re-verify Missing Files: For any file reported as missing, re-run

   list_dir

   on its parent directory to confirm whether the file truly does not exist or whether the path was wrong. Correct the path and retry the single file if necessary.

---

Phase 3 — TypeScript Import Validation

This phase targets a common class of structural bugs found when auditing TypeScript source trees.

10. Identify Import Statements: For every

    .ts

    /

    .tsx

    file read in Phase 2, extract all

    import

    lines.

11. Classify Import Kind — Value vs. Type:

    Pattern	Correct usage
    import Foo from '...'	Runtime value (class, function, object)
    import { Foo } from '...'	Runtime value export
    import type Foo from '...'	Type-only import (erased at compile time)
    import type { Foo } from '...'	Type-only named import
    import { type Foo } from '...'	Inline type modifier (TS 4.5+)

12. Flag Value Imports Used Only as Types: If an identifier imported without

    type

    is used only in type positions (

    : Foo

    ,

    as Foo

    ,

    implements Foo

    , generic parameters), it should be converted to

    import type

    . This prevents accidental runtime dependencies and satisfies

    verbatimModuleSyntax

    /

    isolatedModules

    compiler flags.

    // ❌ Before — value import used only as a type
    import { UserProfile } from './types';
    const handler = (u: UserProfile) => { ... };
    
    // ✅ After — type-only import
    import type { UserProfile } from './types';
    const handler = (u: UserProfile) => { ... };
    

13. Flag Duplicate Imports: Detect cases where the same module is imported more than once in a file (often from copy-paste). Merge them into a single import statement.

    // ❌ Duplicate
    import { A } from './utils';
    import { B } from './utils';
    
    // ✅ Merged
    import { A, B } from './utils';
    

14. Verify Barrel / Index Exports: When a directory contains an

    index.ts

    (barrel file), confirm that every component or module expected to be publicly accessible is re-exported. Cross-reference against the file manifest from Phase 1.

15. Apply Fixes & Re-audit: Apply all import corrections as a single write pass per file. After writing, re-read the affected files (parallel batch) to confirm the fixes took effect.

---

Phase 4 — Final Validation & Report

16. Retry the Original Operation: With the directory structure confirmed and import issues resolved, retry the operation that originally failed.

17. Log an Audit Report: Produce a concise summary covering:

    • Total files enumerated and read
    • Number of batches used (highlight the iteration savings vs. sequential)
    • Shell property check results (line counts, file headers) gathered in Phase 1 at zero extra iteration cost
    • Import issues found and fixed (value→type conversions, duplicate merges, missing barrel exports)
    • Any remaining unresolved issues with recommended next steps

---

Quick Reference: Iteration Collapse Patterns

# Sequential (slow) — N+K iterations for N files + K property checks
list_dir(dir)         → wait
run_shell(wc -l ...)  → wait  ← extra iteration that can be eliminated
read_file(file1)      → wait
read_file(file2)      → wait
...

# Optimized (fast) — 1 + ⌈N/B⌉ iterations
[list_dir(dir), run_shell("head -5 f1 && wc -l f1 && head -5 f2 && wc -l f2")]  ← 1 iteration (Phase 1)
[read_file(file1), read_file(file2), ..., read_file(fileB)]                       ← 1 iteration (Phase 2, batch 1)
[read_file(fileB+1), ...]                                                          ← 1 iteration (Phase 2, batch 2)

Compound Shell Command Templates

# Check header + line count for a single file
head -10 /path/to/file.css && echo "LINES:" && wc -l /path/to/file.css

# Check multiple files in one run_shell call
head -5 /path/to/a.css && echo "LINES_A:" && wc -l /path/to/a.css && \
echo "===" && \
head -5 /path/to/b.ts  && echo "LINES_B:" && wc -l /path/to/b.ts

# Verify a file starts with expected content (e.g., CSS theme comment)
head -1 /path/to/styles.css | grep -q "Theme Colors" && echo "OK" || echo "MISSING HEADER"

# Count files matching a pattern in a directory
ls src/components/*.tsx | wc -l

---

Best Practices

• Co-schedule shell checks with

  list_dir

  : Any

  wc -l

  or

  head -N

  call you know you'll need belongs in the same iteration as your initial

  list_dir

  calls — never in a dedicated follow-up iteration.
• Bundle multiple shell checks into one

  run_shell

  : Use

  &&

  or

  ;

  to chain head/wc/grep commands for multiple files into a single

  run_shell

  invocation. Each

  run_shell

  call costs one tool-call slot; batching them saves slots.
• Always enumerate before reading:

  list_dir

  first, then batch-read. Never guess file names.
• Use absolute paths throughout to avoid working-directory ambiguity.
• Batch by locality: Group files from the same directory in the same batch to keep context coherent.
• Type imports are zero-cost at runtime: Prefer

  import type

  for any symbol used exclusively as a TypeScript type. This is especially important in projects with

  isolatedModules: true

  .
• Barrel files are contracts: Treat

  index.ts

  exports as the public API of a module. Missing exports are bugs even if the underlying file is correct.
• Log intermediate findings: If issues persist after Phase 3, dump the full audit log for offline debugging.

---

Common Fix Categories (Checklist)

• Directory missing → create with

  mkdir -p

• Permissions insufficient →

  chmod

  /

  chown

  or escalate
• Path typo → re-enumerate with

  list_dir

  , correct path
• File has wrong line count → inspect with

  wc -l

  (already gathered in Phase 1 at no extra cost)
• File has wrong header content → inspect with

  head -N

  (already gathered in Phase 1 at no extra cost)
• Value import used as type → add

  import type

• Duplicate imports → merge into single statement
• Missing barrel export → add re-export to

  index.ts

• Circular import → restructure module boundaries