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

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

Reads the history array from settings.json, appends unsaved entries to
week-folder-specific history.jsonl files based on timestamp.
Also mirrors main 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 by 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 from settings.json to save as snapshot
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. Supports '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 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]:
    """Distribute 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 the week's archive.log for the execution 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

Automatically executed 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 specified folder readable by 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/`

Identify "last week (Mon–Sun)" folder using Bash on 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\")}')
"
```

Using the folder name obtained above, read all lines of `history.jsonl`. If the folder does not exist, record "no last week's logs" and finish with output in Steps 7 and 8.

---

## 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; dictionary deletions use last 8 weeks)

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

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

Criteria for identifying the same suggestion:
- dictionary: matching word to add
- replacements: both from and to match
- customInstructions: equivalent meaning (text similarity 80% or higher)

---

## Step 4: Analysis

### 4-1. Detecting dictionary addition candidates

Important: Do not judge based solely on simple divergence between `rawText` and `content` (to avoid false positives where content has been correctly fixed by LLM correction).

Detection targets are cases where problems remain in content (final output):

| Detection condition | Example |
|---|---|
| Notation variation: multiple notations mixed in content for the same intent | Both `Claude` and `クロード` appear |
| Remaining katakana: proper nouns that should be in English appear in katakana in content | `プレジデント` (should be `Presigned`) |
| Remaining mistranslation: clearly different conversion from intent becomes established in content | `蔵人` (should be `Claude`) |

Must not semantically overlap with already registered dictionary words.

### 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 template text 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 | "あー", "えー", "えーと", "あのー", "まあ", "なんか" remain in content 5 or more times each |
| Missing command words | "改行", "かっこ", "かぎかっこ" remain as character strings in content |
| Duplicate rephrasing | Same expression appears consecutively |
| Notation variation (style-related) | Mixed half-width/full-width numbers, inconsistent katakana long vowels, 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):

| Occurrences 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 the 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 occurrences for 4 consecutive weeks
- Dictionary deletion candidates: First proposed only after 8 consecutive weeks of zero occurrences

---

## Step 5: Generate suggestions

Summarize each suggestion in the following format (dictionary additions/deletions, replacements additions/deletions, customInstructions additions):

```
### [Type] Value: <Content>
- Type: <Type>
- Recommendation Rate: XX%
- Frequency Score: XX% (N items this week)
- Continuity Score: XX% (appeared N weeks in 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 and update 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 rate 80% or above)
2. Pending (recommendation rate below 80%)
3. Archived suggestions (if any)
4. This week's statistics

---

## Step 7: Output Notification Summary (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
• Confirmed candidates (80% or above): N
• Pending: N

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

[Pending (Recommendation Rate 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, just send 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 obtain your own user ID
2. Send a DM to the obtained 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 Rate 80% or above)

### [dictionary add] Value: S3
- Type: dictionary add
- Word to add: `S3`
- Detection reason: Appears in content but absent in rawText (correction by deep context)
- Recommendation rate: 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 rate: 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 rate: 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 rate: 85%
- Frequency score: 75% (18 entries this week, in the 10–19 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 rate: 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 rate: 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 rate: 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 rate: 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 (in approximately 5 out of 76 entries it is clearly a filler). It is important to explicitly state in the instruction text to "retain it when used as a meaningful word."

---

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

### [dictionary add] Value: Cognito
- Type: dictionary add
- Word to add: `Cognito`
- Detection reason: content 6 entries / rawText 0 entries
- Recommendation rate: 65%
- Frequency score: 55% (6 entries this week, in the 5–9 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 (variant spelling)
- Type: dictionary add
- Word to add: `Claude`
- Detection reason: "Claude" (7 instances) and "クロード" (4 instances) mixed in content. In rawText, "クロード" is dominant (6 instances), "Claude" is zero.
- Recommendation rate: 55%
- Frequency score: 55% (7 entries this week, in the 5–9 range)
- Continuity score: 0% (no previous suggestion, new)
- Adjustment: none
- Appearance history: [7 items this week (+ 4 mixed instances of クロード), 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 rate: 55%
- Frequency score: 55% (5 entries this week, in the 5–9 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 rate: 50%
- Frequency score: 40% (3 entries this week, in the 3–4 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 rate: 40%
- Frequency score: 40% (4 entries this week, in the 3–4 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 rate: 40%
- Frequency score: 40% (3 entries this week, in the 3–4 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 rate: 40%
- Frequency score: 0% (0 items this week)
- Continuity score: 30% (appeared 1 week in pending over 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 weeks of zero required. Currently only 1 week)

### [dictionary add] Value: Presigned (remaining misrecognition)
- Type: dictionary add
- Word to add: `Presigned`
- Detection reason: In rawText, misrecognized as "プレゼント URL", "プレザイン", etc. Some cases in content also not fully corrected.
- Recommendation rate: 20%
- Frequency score: 20% (2 entries this week, in the 1–2 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
- Confirmed candidates (recommendation rate 80% or above): 8
- Pending (recommendation rate below 80%): 8
- replacements addition candidates: none (no repeating patterns 3 or more times)
- replacements deletion candidates: none
- Usage of major dictionary terms: AgentCore=20 items, Anthropic=8 items, Markdown=8 items, ナレッジ=5 items (all in continued use)

---

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