b267e55f8c
- AGENTS.md: build spec for Paperclip (constraints, conventions, 7 phases) - docs/phase-1..7: per-phase work, DoD, out-of-scope, risks - reference/: frozen decisions, stack+ports+budgets, content map, acceptance tests - agents/: persona and security policy drafts - Retires the React scaffold; history retained as record of the false start
84 lines
4.5 KiB
Markdown
84 lines
4.5 KiB
Markdown
# Phase 1 — Content source of truth
|
||
|
||
**Goal:** `content/` exists, is schema-valid, and covers all six areas. Both later renderers read from it. No site code yet.
|
||
|
||
**Depends on:** nothing. This is the critical path.
|
||
|
||
---
|
||
|
||
## Inputs
|
||
|
||
| Source | Location | What it gives |
|
||
|---|---|---|
|
||
| Evidence notes | `../resume_ai_system/plan/EVIDENCE-NOTES.md` | Devices, systems, platforms, AI work, career, interests — **Sam's own words, the authority** |
|
||
| Recovered content | `../resume_ai_system/plan/draft-content.md` | Client wall, skills, non-IT history, project index |
|
||
| Content spine | `../resume_ai_system/plan/20-content-spine.md` | Areas, claims, metric chips, metadata schema |
|
||
| Résumé | `.27:/home/sam/Downloads/resume_2025.docx` + `.../05_documents/*.docx` | 2000–2020 engagements, education |
|
||
| Old project notes | `../resume_ai_system/old_projects.md` | Code exhibit locations, IoT grouping |
|
||
| Web archive | `03_projects/web_work/` (read-only) | Code excerpts only where named |
|
||
|
||
These paths are outside the repo. **Read them, do not edit them, do not depend on them at build time.** Everything needed must land in `content/`.
|
||
|
||
---
|
||
|
||
## Work
|
||
|
||
1. **Implement the schema** from `AGENTS.md` §7 as a validator (Go or Python — one file, no framework).
|
||
2. **Create the area structure:**
|
||
```
|
||
content/
|
||
ai/ # harnesses, routing, RAG, voice, guardrails, observability
|
||
platform/ # NixOS, packaging, docker, network, backups, signage infra
|
||
edge/ # devices, radio, audio distribution, sensors, failures
|
||
products/ # Audas Media, WebsiteBuilder, Where-Woof
|
||
history/ # 2000–2014 client wall and engagements
|
||
about/ # narrative, non-IT background, education, interests
|
||
assets/ # diagrams, screenshots, logos — optimised
|
||
```
|
||
3. **Author L1 for all six areas** — one screen each: claim, three metric chips, tech chips, one link.
|
||
4. **Author L2 for three areas in full** — `ai`, `platform`, `edge`. These are the three target roles and the proof that the template works.
|
||
5. **Author `products` and `history` at L2** — the commercial story and the client wall. These carry disproportionate weight; do not skimp.
|
||
6. **Author `about` at L2** — narrative, the 2020–2026 framing, non-IT work history, education, interests.
|
||
7. **Create L3 stubs** for every artefact referenced by an L2 page, even if the artefact lands later. A dangling reference fails validation.
|
||
8. **Redaction pass:** no family names, no address, no phone unless Sam confirms, no credentials, no personal data.
|
||
|
||
---
|
||
|
||
## Non-negotiables in content
|
||
|
||
- **Confidence labels are set honestly.** `EVIDENCE-NOTES.md` distinguishes finished, in-progress, postponed and failed. Preserve that distinction exactly.
|
||
- **Numbers must trace to the evidence notes.** The known corrections: **3 businesses currently active** (~12 adopted over time); **Where-Woof deployed, not yet to market**; drop unverified figures like "42 devices" and "800ms end-to-end".
|
||
- **Failures stay in.** The lizard feeder destroyed by the lizard, the postponed garden cameras, the doorbell being rebuilt. They are evidence of production experience.
|
||
- **Framing rule** from `AGENTS.md` §7 — capability first, product name second.
|
||
|
||
---
|
||
|
||
## Definition of Done
|
||
|
||
- [ ] `content/` validates cleanly against the schema; validator exits non-zero on any violation.
|
||
- [ ] Six areas exist, each with an L1 entry.
|
||
- [ ] `ai`, `platform`, `edge`, `products`, `history`, `about` each have an L2 entry.
|
||
- [ ] Every L2 references only artefacts that exist as L3 stubs.
|
||
- [ ] Every `metric` value appears in the evidence notes — **no invented numbers**.
|
||
- [ ] Every entry has a `confidence` and a `last_verified` date.
|
||
- [ ] The redaction pass is documented (a list of what was excluded and why).
|
||
- [ ] `git log` shows the content commit; `make validate` (or equivalent) passes.
|
||
|
||
---
|
||
|
||
## Out of scope
|
||
|
||
- Rendering. No HTML, no templates, no CSS.
|
||
- Choosing a logo set — Phase 7.
|
||
- Writing the persona or security policy — Phase 5/6, drafts exist in `agents/`.
|
||
|
||
---
|
||
|
||
## Risks
|
||
|
||
| Risk | Mitigation |
|
||
|---|---|
|
||
| Content drifts into invented detail (the historical failure) | Every metric must trace to evidence; the validator enforces a `confidence` field; Sam reviews before Phase 2 signs off |
|
||
| Over-authoring — 40 pages where 12 suffice | L1 ×6, L2 ×6, L3 stubs only. Depth is added when a specific question demands it |
|
||
| Schema churn after content is written | Freeze the schema in this phase. Changing it later means re-touching every file — treat it as a breaking change |
|