docs: tiny transformer implementation plan for scam/spam classifier

.agent/skills/simpledoc/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: simpledoc
+description: Create or update documentation in this repo following SimpleDoc conventions. Use when creating docs, plans, logs, or any markdown files.
+---
+
+# SimpleDoc Documentation Skill
+
+**Attention agent!** Complete every item below before touching documentation work:
+
+1. **Read this file in full for the current session.** No shortcuts.
+2. **Verify that git is initialized and configured.** You will need the name and email of the current user in order to populate the `author` field in the YAML frontmatter. Run the following one-liner to verify:
+
+```bash
+printf '%s <%s>\n' "$(git config --local --get user.name 2>/dev/null || git config --global --get user.name)" "$(git config --local --get user.email 2>/dev/null || git config --global --get user.email)"
+```
+
+If the name and email are not available for some reason, ask the user to provide them, and also setup git configuration for them.
+
+## SimpleDoc Specification
+
+SimpleDoc defines two types of files:
+
+1. **Date-prefixed files**: SHOULD be used for most documents, e.g. `docs/2025-12-22-an-awesome-doc.md`.
+2. **Capitalized files**: SHOULD be used for general documents that are not tied to a specific time, e.g. `README.md`.
+
+### 1. Date-prefixed files
+
+- MUST put date-prefixed files in a top level `docs/` folder, or a subfolder `docs/<topic>/`. Subfolders MAY be nested indefinitely.
+- MUST use ISO 8601 date prefixes (`YYYY-MM-DD`) — the date MUST contain dashes.
+- After the date prefix, lowercase filenames SHOULD use dashes (`-`) as word delimiters (kebab-case). Avoid spaces and underscores.
+- The date prefix MAY be the entire filename (for example, daily logs like `docs/logs/2026-02-04.md`).
+- MUST NOT use capital letters in filename for Latin, Greek, Cyrillic and other writing systems that have lowercase/uppercase distinction.
+- MAY use non-ASCII characters.
+- Date-prefixed files SHOULD contain YAML frontmatter with at least `title`, `author` and `date` fields:
+  ```yaml
+  ---
+  title: Implementation Plan
+  author: John Doe <john.doe@example.com>
+  date: 2025-12-22
+  ---
+  ```
+- If present in YAML frontmatter, author SHOULD be of `Name <email>` per the RFC 5322 name-addr mailbox format and date SHOULD be ISO 8601 `YYYY-MM-DD` format.
+
+### 2. Capitalized files
+
+- For general documents not tied to a specific time, e.g. `README.md`, `AGENTS.md`, `INSTALL.md`, `HOW_TO_DEBUG.md`.
+- Multi-word filenames SHOULD use underscores (`CODE_OF_CONDUCT.md`).
+
+## Preferences in Documentation Style
+
+- Tone: casual, clear, technically precise but not academic
+- Planning docs: concrete and actionable, include checklists
+- Keep docs concise — no fluff, no filler paragraphs
+- Use ISO timestamps where relevant
+- Prefer bullet points over prose for technical content
+
+## Before You Start
+
+1. Run `date +%Y-%m-%d` and use the output for both filename prefix and `date` field.
+2. Identify where the document belongs:
+   - Keep general documentation at the root of `docs/`.
+   - Use dedicated subdirectories for specialized content (plans, logs, reports).
+3. Check for existing, related docs to avoid duplicates and to link to prior work.
+
+## File Naming
+
+- Format: `YYYY-MM-DD-descriptive-title.md`. The date MUST use dashes; the rest SHOULD be lowercase with hyphens (avoid underscores).
+- Choose names that reflect the problem or topic, not the team or author.
+- Example: `2025-06-20-api-migration-guide.md`.
+- Place the file in the appropriate folder before committing.
+
+### Timeless vs. Dated
+
+- **Timeless general documents** describe enduring processes or repo-wide rules. They do not carry a date prefix and keep their canonical names.
+- **All other content** (design notes, incidents, feature guides, migrations, meeting notes, plans, etc.) must use the date-prefixed naming pattern above.
+- When adding or reviewing documentation, decide which bucket applies.
+
+## Required Front Matter
+
+Every doc **must** start with YAML front matter:
+
+```yaml
+---
+date: 2025-10-24 # From `date +%Y-%m-%d`
+author: Name <email@example.com>
+title: Short Descriptive Title
+tags: [tag1, tag2] # Optional but recommended
+---
+```
+
+## Daily Logs (SimpleLog)
+
+Default location: `docs/logs/YYYY-MM-DD.md`.
+
+### Create a daily log entry
+
+```bash
+npx -y @simpledoc/simpledoc log "Entry text here"
+```
+
+For multiline:
+```bash
+cat <<'EOF' | npx -y @simpledoc/simpledoc log --stdin
+Multiline entry here
+- point one
+- point two
+EOF
+```
+
+### Manual edits (if needed)
+
+- Keep the YAML frontmatter intact (`title`, `author`, `date`, `tz`, `created`, optional `updated`).
+- Ensure a blank line separates entries.
+- Session sections must be `## HH:MM` (local time of the first entry in that section).
+
+### Ongoing logging
+
+Log anything worth noting: significant changes, decisions, errors, workarounds, progress. Log each entry after completing the step. No exceptions.
+
+## Final Checks Before Submitting
+
+- [ ] Filename follows the `YYYY-MM-DD-…` pattern and lives in the correct directory.
+- [ ] Front matter is complete and accurate.
+- [ ] Links to related documentation exist where applicable.
+- [ ] Run `npx -y @simpledoc/simpledoc check` to verify SimpleDoc conventions.

AGENTS.md

@@ -74,7 +74,7 @@ Janitr/
 │   └── logs/            # Daily development logs
 │
 ├── tests/               # Integration tests
-└── skills/              # Agent skills (SimpleDoc)
+└── .agent/skills/       # Agent skills (SimpleDoc, etc.)
 ```
 
 ---
@@ -159,7 +159,7 @@ Thresholds are tuned per-label to maintain FPR < 2%. The `promo` label is curren
 
 ## SimpleDoc Conventions
 
-**Attention agent!** Before creating ANY documentation, use the `simpledoc` skill in `skills/simpledoc/SKILL.md`.
+**Attention agent!** Before creating ANY documentation, use the `simpledoc` skill in `.agent/skills/simpledoc/SKILL.md`.
 
 Key rules:
 

docs/logs/2026-02-13.md

@@ -0,0 +1,36 @@
+---
+title: Daily Log 2026-02-13
+author: bob <unknown@example.com>
+date: 2026-02-13
+tz: Europe/Berlin
+created: 2026-02-13T08:26:22+01:00
+last_section: 2026-02-13T09:08:18+01:00
+updated: 2026-02-13T09:09:50+01:00
+---
+
+## 08:26
+
+Planning tiny-transformer implementation doc for janitr. Gathered current context from scripts/prepare_data.py, scripts/prepare_hf.py, scripts/evaluate.py, extension/offscreen.js, extension/background.js, and data/replies\*.jsonl. Key constraint observed: only 14 ground-truth ai_generated_reply rows currently in data/replies.jsonl, so plan will include data expansion + teacher distillation before student deployment.
+
+Created docs/plans/2026-02-13-tiny-transformer-plan.md with a concrete implementation plan for the tiny-transformer option.
+
+Included:
+
+- explicit student architecture (4 layers, hidden 192, 4 heads, seq len 96)
+- tokenizer strategy (custom WordPiece 8k)
+- data-prep workflow grounded on data/replies.jsonl, data/replies_inferred.jsonl, data/sample.jsonl
+- teacher training + distillation + quantization pipeline
+- ONNX export acceptance criteria
+- extension integration points (background/offscreen/content-script/manifest)
+- offline + runtime evaluation gates
+- model/bundle size estimates
+
+Ran `npx @simpledoc/simpledoc check` after writing; it failed only on filename convention and suggested renaming to a date-prefixed filename. Kept the user-requested path `docs/plans/2026-02-13-tiny-transformer-plan.md` intentionally.
+
+## 09:08
+
+Reviewed current tiny-transformer plan and baseline Janitr fastText pipeline. Preparing full rewrite of docs/plans/2026-02-13-tiny-transformer-plan.md to target existing scam/topic_crypto/clean classifier, incorporate teacher-model research, and remove all ai_reply references.
+
+Rewrote docs/plans/2026-02-13-tiny-transformer-plan.md to target Janitr's existing scam/topic_crypto/clean classifier instead of ai_reply. Updated dataset baseline counts, teacher model choices (TimeLM primary, BERTweet alternative), distillation strategy (calibration, T=2-4, alpha schedule, hidden-state matching), DAPT/logit-caching plan, extension integration references, script names, evaluation gates, and added updated timestamp.
+
+Ran npx -y @simpledoc/simpledoc check after rewrite. Check failed because docs/plans/2026-02-13-tiny-transformer-plan.md is not date-prefixed per current SimpleDoc naming convention; migration would rename file and update docs/logs references. Kept filename unchanged this turn because user requested direct rewrite of that exact path.