Aqua Voice × Claude Cowork: Systematizing Voice Input Customization with Automated Weekly Analysis

#$HOME/Library/Application Support/aqua-voice-archive/aqua_archive.py
"""
Script that permanently archives Aqua Voice transcription history to a specified folder.

Reads the history array from settings.json and appends unsaved entries to
week folder-specific history.jsonl files based on their timestamps.
Also mirrors key settings such as dictionary / replacements / customInstructions
to settings-snapshot.json (so they can be referenced from Cowork).
"""

import json
import os
import sys
import traceback
from datetime import datetime, timedelta, timezone
from pathlib import Path

HOME = Path.home()
SETTINGS_PATH = HOME / "Library/Application Support/Aqua Voice/settings.json"
# Archive save destination (any folder readable from Cowork is fine)
ARCHIVE_DIR = Path("<ARCHIVE_PATH>")
SNAPSHOT_PATH = ARCHIVE_DIR / "snapshot.json"
SETTINGS_SNAPSHOT_PATH = ARCHIVE_DIR / "settings-snapshot.json"
DATA_DIR = ARCHIVE_DIR / "data"

# Main keys to save from settings.json
SETTINGS_SNAPSHOT_KEYS = [
    "dictionary",
    "replacements",
    "customInstructions",
    "transcriptionModel",
    "language",
    "deepContext",
    "casualMessaging",
    "promptSet",
    "computerControlCustomInstructions",
]

# JST (UTC+9) fixed. Aqua Voice timestamps are UTC so conversion is needed
JST = timezone(timedelta(hours=9))

def parse_iso_to_jst(iso_str: str) -> datetime:
    """Convert ISO 8601 string to JST datetime. Handles 'Z' suffix."""
    normalized = iso_str.replace("Z", "+00:00")
    dt_utc = datetime.fromisoformat(normalized)
    return dt_utc.astimezone(JST)

def week_folder_name(dt_jst: datetime) -> str:
    """Generate Monday-based week folder name from JST datetime (YYYY-MMDD_YYYY-MMDD)."""
    days_since_monday = dt_jst.weekday()
    monday = dt_jst.date() - timedelta(days=days_since_monday)
    sunday = monday + timedelta(days=6)
    return f"{monday.strftime('%Y-%m%d')}_{sunday.strftime('%Y-%m%d')}"

def collect_known_session_ids() -> set[int]:
    """Collect known sessionIds from all history.jsonl files under data/."""
    known: set[int] = set()
    if not DATA_DIR.exists():
        return known
    for jsonl_path in DATA_DIR.glob("*/history.jsonl"):
        try:
            with jsonl_path.open("r", encoding="utf-8") as f:
                for line in f:
                    line = line.strip()
                    if not line:
                        continue
                    try:
                        entry = json.loads(line)
                        sid = entry.get("sessionId")
                        if sid is not None:
                            known.add(sid)
                    except json.JSONDecodeError:
                        continue
        except OSError:
            continue
    return known

def append_entries_to_week(entries: list[dict]) -> dict[str, int]:
    """Sort entries by week folder and append to history.jsonl."""
    by_week: dict[str, list[dict]] = {}
    for entry in entries:
        ts = entry.get("timestamp")
        if not ts:
            continue
        try:
            dt_jst = parse_iso_to_jst(ts)
        except ValueError:
            continue
        week_name = week_folder_name(dt_jst)
        by_week.setdefault(week_name, []).append(entry)

    result: dict[str, int] = {}
    for week_name, week_entries in by_week.items():
        week_dir = DATA_DIR / week_name
        week_dir.mkdir(parents=True, exist_ok=True)
        week_entries.sort(key=lambda e: e.get("timestamp", ""))
        jsonl_path = week_dir / "history.jsonl"
        with jsonl_path.open("a", encoding="utf-8") as f:
            for entry in week_entries:
                f.write(json.dumps(entry, ensure_ascii=False) + "\n")
        result[week_name] = len(week_entries)
    return result

def write_archive_log(lines: list[str]) -> None:
    """Append operation log to archive.log for the week containing the current time."""
    now_jst = datetime.now(JST)
    week_name = week_folder_name(now_jst)
    week_dir = DATA_DIR / week_name
    week_dir.mkdir(parents=True, exist_ok=True)
    log_path = week_dir / "archive.log"
    with log_path.open("a", encoding="utf-8") as f:
        for line in lines:
            f.write(line + "\n")
        f.write("---\n")

def main() -> int:
    log_lines: list[str] = []
    now_str = datetime.now(JST).strftime("%Y-%m-%d %H:%M:%S")
    log_lines.append(f"[{now_str}] start")

    if not SETTINGS_PATH.exists():
        log_lines.append(f"[{now_str}] error: settings.json not found at {SETTINGS_PATH}")
        write_archive_log(log_lines)
        return 1

    try:
        with SETTINGS_PATH.open("r", encoding="utf-8") as f:
            settings = json.load(f)
    except (OSError, json.JSONDecodeError) as e:
        log_lines.append(f"[{now_str}] error: failed to read settings.json: {e}")
        write_archive_log(log_lines)
        return 1

    history = settings.get("history", [])
    if not isinstance(history, list):
        log_lines.append(f"[{now_str}] error: history is not a list")
        write_archive_log(log_lines)
        return 1

    log_lines.append(f"[{now_str}] settings.json read: {len(history)} entries")

    known_ids = collect_known_session_ids()
    log_lines.append(f"[{now_str}] known sessionIds: {len(known_ids)}")

    new_entries = [
        e for e in history
        if isinstance(e, dict) and e.get("sessionId") is not None and e["sessionId"] not in known_ids
    ]
    log_lines.append(f"[{now_str}] new entries detected: {len(new_entries)}")

    if new_entries:
        result = append_entries_to_week(new_entries)
        for week_name in sorted(result.keys()):
            log_lines.append(f"[{now_str}] appended: {week_name}/history.jsonl  +{result[week_name]} entries")
    else:
        log_lines.append(f"[{now_str}] skip (no new entries, but snapshot refreshed)")

    try:
        ARCHIVE_DIR.mkdir(parents=True, exist_ok=True)
        with SNAPSHOT_PATH.open("w", encoding="utf-8") as f:
            json.dump(history, f, ensure_ascii=False, indent=2)
        log_lines.append(f"[{now_str}] snapshot.json updated")
    except OSError as e:
        log_lines.append(f"[{now_str}] error: failed to write snapshot.json: {e}")
        write_archive_log(log_lines)
        return 1

    try:
        settings_snapshot = {"snapshotAt": datetime.now(JST).isoformat()}
        for key in SETTINGS_SNAPSHOT_KEYS:
            settings_snapshot[key] = settings.get(key)
        with SETTINGS_SNAPSHOT_PATH.open("w", encoding="utf-8") as f:
            json.dump(settings_snapshot, f, ensure_ascii=False, indent=2)
        log_lines.append(f"[{now_str}] settings-snapshot.json updated")
    except OSError as e:
        log_lines.append(f"[{now_str}] error: failed to write settings-snapshot.json: {e}")
        write_archive_log(log_lines)
        return 1

    end_str = datetime.now(JST).strftime("%Y-%m-%d %H:%M:%S")
    log_lines.append(f"[{end_str}] done")
    write_archive_log(log_lines)
    return 0

if __name__ == "__main__":
    try:
        sys.exit(main())
    except Exception:
        traceback.print_exc(file=sys.stderr)
        sys.exit(1)

---
name: aqua-voice-weekly-analysis
description: Aqua Voice weekly settings analysis — Generate improvement suggestions for dictionary, replacements, and customInstructions and save to knowledge base
---

# Aqua Voice Weekly Settings Analysis Task

Runs automatically every Monday at 01:00. Analyzes Aqua Voice voice logs, generates improvement suggestions for dictionary, replacements, and customInstructions, saves them to the knowledge base, and notifies Slack.

All data is mirror-saved to a designated folder readable from Cowork. Do not directly access `~/Library/Application Support/` (cannot be read from sandbox).

---

## Step 1: Identify and Load Last Week's history.jsonl

Archive directory:
`<ARCHIVE_PATH>/data/`

Use Bash to identify the "previous week (Mon-Sun)" folder from the execution date (Monday):

```bash
python3 -c "
from datetime import datetime, timedelta
today = datetime.today()
last_monday = today - timedelta(days=today.weekday() + 7)
last_sunday = last_monday + timedelta(days=6)
print(f'{last_monday.strftime(\"%Y-%m%d\")}_{last_sunday.strftime(\"%Y-%m%d\")}')
"
```

Use the folder name obtained above to read all lines of `history.jsonl`. If the folder doesn't exist, record "No log from last week" and output in Steps 7 and 8, then end.

---

## Step 2: Load Current Settings Snapshot

Load the following file:
`<ARCHIVE_PATH>/settings-snapshot.json`

Keys included: `dictionary`, `replacements`, `customInstructions`, `transcriptionModel`, `language`, `deepContext`, `casualMessaging`, `promptSet`, `computerControlCustomInstructions`, `snapshotAt`

---

## Step 3: Load Past Suggestion Files (Last 4 weeks; 8 weeks for dictionary deletion)

Load `aqua-voice-suggestions-*.md` files under `<KNOWLEDGE_PATH>/notes/`, 4 weeks for addition candidates and 8 weeks for dictionary deletion candidates.

For each suggestion, aggregate the following from past files:
- Number of weeks appeared (for calculating continuation score)
- Appearance count per week (history)

Criteria for judging same suggestion:
- dictionary: word to add matches
- replacements: both from and to match
- customInstructions: meaning is equivalent (text similarity 80% or above)

---

## Step 4: Analysis

### 4-1. Detecting dictionary Addition Candidates

Important: Don't judge based on simple divergence between `rawText` and `content` alone (to avoid false positives where LLM correction has correctly fixed content).

Target cases where problems remain in content (final output):

| Detection condition | Example |
|---|---|
| Spelling variations: Multiple expressions mixed in content for the same intent | Both `Claude` and `クロード` appear |
| Remaining katakana: Proper noun that should be in English notation appears in katakana in content | `プレジデント` (should be `Presigned`) |
| Remaining misconversion: Clearly different conversion from intent that has become established in content | `蔵人` (should be `Claude`) |

Must not semantically duplicate words already registered in dictionary.

### 4-2. Detecting dictionary Deletion Candidates

Among existing dictionary registered words, those that have not appeared in either content or rawText for 8 consecutive weeks.

### 4-3. Detecting replacements Addition Candidates

- The same URL, command, or fixed phrase appears 3 or more times in content, including similar patterns
- Always present "from (spoken phrase) → to (converted text)" as a pair

### 4-4. Detecting replacements Deletion Candidates

The `from` phrase of existing replacements has not appeared in either content or rawText for 8 consecutive weeks.

### 4-5. Detecting customInstructions Addition Candidates

| Category | Detection condition |
|---|---|
| Filler removal | "あー", "えー", "えーと", "あのー", "まあ", "なんか" each remain 5+ times in content |
| Missing command words | "改行", "かっこ", "かぎかっこ" remain as strings in content |
| Duplicate rephrasing | Same expression appears consecutively |
| Spelling variations (style) | Mixed half-width/full-width numbers, inconsistent presence/absence of katakana long vowel marks, etc. |

### 4-6. Recommendation Score Calculation Logic (Common to All Types)

```
Recommendation score = max(frequency score, continuation score) + match bonus + decay
```

Frequency score (strength of this week alone):

| Appearances this week | Score |
|---|---|
| 20 or more | 90% |
| 10-19 | 75% |
| 5-9 | 55% |
| 3-4 | 40% |
| 1-2 | 20% |
| 0 | 0% |

Continuation score (number of weeks appeared in last 4 weeks):

| Weeks appeared | Score |
|---|---|
| 4 consecutive weeks | 95% |
| 3 weeks | 75% |
| 2 weeks | 55% |
| 1 week | 30% |
| 0 weeks | 0% |

- Match bonus (matches past pending suggestion): +10%
- Decay (0 occurrences this week + exists only as past pending): -15%
- Recommendation score clipped to 0-100%

Auto-archive:
- Addition candidates: Remove from suggestion list if zero appearances for 4 consecutive weeks
- dictionary deletion candidates: Only suggest after 8 consecutive weeks of zero

---

## Step 5: Generate Suggestions

Summarize each suggestion in the following format (dictionary addition/deletion, replacements addition/deletion, customInstructions addition):

```
### [Type] Value: <Content>
- Type: <Type>
- Recommendation Score: XX%
- Frequency Score: XX% (N items this week)
- Continuity Score: XX% (appeared N weeks out of the last 4 weeks)
- Adjustment: +10% / -15% / none
- Appearance History: [N items this week, N items 1 week ago, N items 2 weeks ago, N items 3 weeks ago]
- Status: Confirmed Candidate (80% or above) / Pending (below 80%)
```

---

## Step 6: Saving to Knowledge Base

Create a Markdown file at the following path (overwrite if file already exists):

`<KNOWLEDGE_PATH>/notes/aqua-voice-suggestions-YYYY-MM-DD.md`

Front matter:
```yaml
---
created: YYYY-MM-DD
tags: [aqua-voice, wip]
summary: Aqua Voice Weekly Analysis YYYY-MM-DD - N confirmed candidates, N pending
---
```

Body structure:
1. Confirmed Candidates (recommendation score 80% or above)
2. Pending (recommendation score below 80%)
3. Archived suggestions (if any)
4. This week's statistics

---

## Step 7: Notification Summary Output (Chat)

Always write the file path as a full path.

```
Aqua Voice Weekly Analysis Report YYYY-MM-DD

[This Week's Statistics]
• Number of analyzed entries: N items
• Confirmed candidates (80% or above): N items
• Pending: N items

[Confirmed Candidates (Recommendation Score 80% or above)]
• [dictionary add] <word> — Recommendation Score XX% (N items this week, appeared N weeks out of last 4 weeks)
• [replacements add] from "<utterance>" → to "<conversion target>" — Recommendation Score XX%
• [customInstructions add] <category>: <one-line description> — Recommendation Score XX%

[Pending (Recommendation Score below 80%)]
(same as above)

[Detail File]
<KNOWLEDGE_PATH>/notes/aqua-voice-suggestions-YYYY-MM-DD.md
```

If both confirmed candidates and pending are 0 items, send only a short message saying "No suggestions this week."

---

## Step 8: Slack DM Notification to Self

1. Search for `<YOUR_SLACK_EMAIL>` using `slack_search_users` to get your own user ID
2. Send a DM to the retrieved user ID using `slack_send_message`

If Slack MCP is unavailable or sending fails, note that fact only in the chat output and finish.

---
created: 2026-05-24
tags: [aqua-voice, wip]
summary: AquaVoice Weekly Analysis 2026-05-24 - 8 confirmed candidates, 8 pending (analyzed 596 items from 2026-0511 to 0517)
---

# AquaVoice Weekly Analysis Report 2026-05-24

Target week: 2026-0511 to 2026-0517 (596 items). Settings snapshot: 2026-05-24T18:53:37+09:00.

---

## 1. Confirmed Candidates (Recommendation Score 80% or above)

### [dictionary add] Value: S3
- Type: dictionary add
- Word to add: `S3`
- Detection reason: Appears in content but absent in rawText (corrected via deep context)
- Recommendation Score: 100%
- Frequency Score: 90% (appeared in 31 entries this week)
- Continuity Score: 30% (appeared in 1 week out of last 4 weeks)
- Adjustment: +10% (matches past pending)
- Appearance History: [31 items this week, 1 week ago -, 2 weeks ago -, 3 weeks ago -]
- Status: **Confirmed Candidate**

### [dictionary add] Value: RDS
- Type: dictionary add
- Word to add: `RDS`
- Detection reason: Appears in content but absent in rawText (misrecognized as "RTS" etc.)
- Recommendation Score: 100%
- Frequency Score: 90% (appeared in 29 entries this week)
- Continuity Score: 30% (appeared in 1 week out of last 4 weeks)
- Adjustment: +10% (matches past pending)
- Appearance History: [29 items this week, 1 week ago -, 2 weeks ago -, 3 weeks ago -]
- Status: **Confirmed Candidate**

### [dictionary add] Value: AWS
- Type: dictionary add
- Word to add: `AWS`
- Detection reason: Appears in content but absent in rawText
- Recommendation Score: 100%
- Frequency Score: 90% (appeared in 24 entries this week)
- Continuity Score: 30% (appeared in 1 week out of last 4 weeks)
- Adjustment: +10% (matches past pending)
- Appearance History: [24 items this week, 1 week ago -, 2 weeks ago -, 3 weeks ago -]
- Status: **Confirmed Candidate**

### [dictionary add] Value: VPC
- Type: dictionary add
- Word to add: `VPC`
- Detection reason: content 18 entries / rawText 20 entries (also appears in rawText but with correction discrepancy)
- Recommendation Score: 85%
- Frequency Score: 75% (18 entries this week, 10-19 item range)
- Continuity Score: 30% (appeared in 1 week out of last 4 weeks)
- Adjustment: +10% (matches past pending)
- Appearance History: [18 items this week, 1 week ago -, 2 weeks ago -, 3 weeks ago -]
- Status: **Confirmed Candidate**

### [dictionary add] Value: Fargate
- Type: dictionary add
- Word to add: `Fargate`
- Detection reason: Appears in content but absent in rawText
- Recommendation Score: 85%
- Frequency Score: 75% (10 entries this week)
- Continuity Score: 30% (appeared in 1 week out of last 4 weeks)
- Adjustment: +10% (matches past pending)
- Appearance History: [10 items this week, 1 week ago -, 2 weeks ago -, 3 weeks ago -]
- Status: **Confirmed Candidate**

### [dictionary add] Value: LLM
- Type: dictionary add
- Word to add: `LLM`
- Detection reason: Appears in content but absent in rawText
- Recommendation Score: 85%
- Frequency Score: 75% (10 entries this week)
- Continuity Score: 30% (appeared in 1 week out of last 4 weeks)
- Adjustment: +10% (matches past pending)
- Appearance History: [10 items this week, 1 week ago -, 2 weeks ago -, 3 weeks ago -]
- Status: **Confirmed Candidate**

### [dictionary add] Value: Bedrock
- Type: dictionary add
- Word to add: `Bedrock`
- Detection reason: Appears in content but absent in rawText
- Recommendation Score: 85%
- Frequency Score: 75% (10 entries this week)
- Continuity Score: 30% (appeared in 1 week out of last 4 weeks)
- Adjustment: +10% (matches past pending)
- Appearance History: [10 items this week, 1 week ago -, 2 weeks ago -, 3 weeks ago -]
- Status: **Confirmed Candidate**

### [customInstructions add] Filler Removal
- Type: customInstructions add
- Category: Filler removal
- Instruction text to register (English recommended, copy-paste ready):
  ```
  Remove filler words and verbal tics from the transcription output. Specifically, remove or omit: 「なんか」「まあ」「えー」「えーと」「あのー」when used as fillers (not meaningful words). Do not remove these if they carry semantic meaning.
  ```
- Recommendation Score: 100%
- Frequency Score: 90% (なんか=99 times, まあ=22 times, えー=7 times remaining in content)
- Continuity Score: 30% (appeared in 1 week out of last 4 weeks)
- Adjustment: +10% (matches past pending)
- Appearance History: [this week なんか99/まあ22/えー7/えーと4, 1 week ago -, 2 weeks ago -, 3 weeks ago -]
- Status: **Confirmed Candidate**
- Note: 「なんか」 is often used as a meaningful word (clearly filler in about 5 out of 76 entries). It is important to explicitly state in the instruction text "keep meaningful words."

---

## 2. Pending (Recommendation Score below 80%)

### [dictionary add] Value: Cognito
- Type: dictionary add
- Word to add: `Cognito`
- Detection reason: content 6 entries / rawText 0 entries
- Recommendation Score: 65%
- Frequency Score: 55% (6 entries this week, 5-9 item range)
- Continuity Score: 30% (appeared in 1 week out of last 4 weeks)
- Adjustment: +10% (matches past pending)
- Appearance History: [6 items this week, 1 week ago -, 2 weeks ago -, 3 weeks ago -]
- Status: Pending

### [dictionary add] Value: Claude (spelling variation)
- Type: dictionary add
- Word to add: `Claude`
- Detection reason: "Claude" (7 items) and "クロード" (4 items) mixed in content. In rawText, "クロード" is dominant (6 items), "Claude" is zero.
- Recommendation Score: 55%
- Frequency Score: 55% (7 entries this week, 5-9 item range)
- Continuity Score: 0% (no previous suggestion, new)
- Adjustment: none
- Appearance History: [7 items this week (+ クロード 4 items mixed), 1 week ago -, 2 weeks ago -, 3 weeks ago -]
- Status: Pending (new)
- Note: Anthropic is already registered. Adding Claude alone is expected to unify "クロード" → "Claude."

### [dictionary add] Value: CloudWatch
- Type: dictionary add
- Word to add: `CloudWatch`
- Detection reason: content 5 entries / rawText 0 entries (misrecognized as "クラウドウォッチドッグス" etc.)
- Recommendation Score: 55%
- Frequency Score: 55% (5 entries this week, 5-9 item range)
- Continuity Score: 0% (no previous suggestion, new)
- Adjustment: none
- Appearance History: [5 items this week, 1 week ago -, 2 weeks ago -, 3 weeks ago -]
- Status: Pending (new)

### [dictionary add] Value: HubSpot
- Type: dictionary add
- Word to add: `HubSpot`
- Detection reason: content 3 entries / rawText 0 entries
- Recommendation Score: 50%
- Frequency Score: 40% (3 entries this week, 3-4 item range)
- Continuity Score: 30% (appeared in 1 week out of last 4 weeks)
- Adjustment: +10% (matches past pending)
- Appearance History: [3 items this week, 1 week ago -, 2 weeks ago -, 3 weeks ago -]
- Status: Pending

### [dictionary add] Value: ALB
- Type: dictionary add
- Word to add: `ALB`
- Detection reason: content 4 entries / rawText 0 entries
- Recommendation Score: 40%
- Frequency Score: 40% (4 entries this week, 3-4 item range)
- Continuity Score: 0% (no previous suggestion, new)
- Adjustment: none
- Appearance History: [4 items this week, 1 week ago -, 2 weeks ago -, 3 weeks ago -]
- Status: Pending (new)

### [dictionary add] Value: IAM
- Type: dictionary add
- Word to add: `IAM`
- Detection reason: content 3 entries / rawText 0 entries
- Recommendation Score: 40%
- Frequency Score: 40% (3 entries this week, 3-4 item range)
- Continuity Score: 0% (no previous suggestion, new)
- Adjustment: none
- Appearance History: [3 items this week, 1 week ago -, 2 weeks ago -, 3 weeks ago -]
- Status: Pending (new)

### [dictionary delete] Antigravity / GenU / Skills / ハーネスエンジニアリング / 冗長化 / NATGateway
- Type: dictionary delete
- Target words: `Antigravity`, `GenU`, `Skills`, `ハーネスエンジニアリング`, `冗長化`, `NATGateway`
- Detection reason: Zero appearances in both content and rawText this week
- Recommendation Score: 40%
- Frequency Score: 0% (0 items this week)
- Continuity Score: 30% (appeared in pending for 1 week out of last 4 weeks)
- Adjustment: +10% (matches past pending)
- Appearance History: [0 items this week, 1 week ago -, 2 weeks ago -, 3 weeks ago -]
- Status: Pending (8 consecutive zero weeks required. Currently only 1 week)

### [dictionary add] Value: Presigned (remaining misrecognition)
- Type: dictionary add
- Word to add: `Presigned`
- Detection reason: Misrecognized in rawText as "プレゼント URL", "プレザイン". Some cases also not fully corrected in content.
- Recommendation Score: 20%
- Frequency Score: 20% (2 entries this week, 1-2 item range)
- Continuity Score: 0% (no previous suggestion, new)
- Adjustment: none
- Appearance History: [2 items this week, 1 week ago -, 2 weeks ago -, 3 weeks ago -]
- Status: Pending (new)

---

## 3. Archived Suggestions

None

---

## 4. This Week's Statistics

- Number of analyzed entries: 596 items
- Confirmed candidates (recommendation score 80% or above): 8 items
- Pending (recommendation score below 80%): 8 items
- replacements addition candidates: none (no repeating patterns 3 or more times)
- replacements deletion candidates: none
- Usage status of major dictionary words: AgentCore=20 items, Anthropic=8 items, Markdown=8 items, ナレッジ=5 items (all still in active use)

---

_Auto-generated: AquaVoice weekly analysis task (run on 2026-05-24). Apply changes manually._