diff --git a/README.md b/README.md index 2597985..d0e1441 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ npm run verify - `app.js` — bilingual workflow, repository-tree, routing, and skill interactions - `responsive.css` — interactive diagrams and Full HD-to-4K adaptations - `docs/references/` — bundled research sources and notes +- `docs/operations-guide.md` — canonical SilverBullet operations and skills guide - `GATES.md` — acceptance ledger for the project ## Publishing @@ -46,6 +47,9 @@ the repository’s `pages` branch exists. Gitea itself does not provide a built-in Pages server; this setup uses the instance’s separate Pages Server and Actions deployment path. +For the complete authoring, verification, publication, rollback, worktree, and +skill workflow, see [docs/operations-guide.md](docs/operations-guide.md). + ## Research See [docs/references/README.md](docs/references/README.md) for official Claude, diff --git a/docs/operations-guide.md b/docs/operations-guide.md new file mode 100644 index 0000000..9c6c939 --- /dev/null +++ b/docs/operations-guide.md @@ -0,0 +1,359 @@ +--- +name: Guides/AI For Dummies Presentation +tags: + - guide + - ai + - skills + - agents + - worktrees + - gitea + - pages +--- + +# AI For Dummies — authoring and operations guide + +This guide explains how to maintain the **AI For Dummies** presentation, how +Gitea Pages is updated, and how the skills, subagents, model routing, and Git +worktree practices taught by the presentation fit together. + +## Quick links + +| Resource | Location | +| :--- | :--- | +| Live presentation | [https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/](https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/) | +| Gitea repository | [https://git.marcospaulo.dev.br/netcracker/ai-for-dummies](https://git.marcospaulo.dev.br/netcracker/ai-for-dummies) | +| Local checkout | `/home/marcos/Projects/ai-for-dummies` | +| Source branch | `main` | +| Published branch | `pages` | +| Local verification | `npm run verify` | +| SilverBullet page | `Guides/AI For Dummies Presentation` | + +## How the site is built + +The presentation is deliberately dependency-free. Gitea Pages serves the +repository files directly; there is no bundler or generated `dist/` folder. + +| File | Responsibility | +| :--- | :--- | +| `index.html` | Semantic sections, controls, labels, and English source copy | +| `styles.css` | Base editorial visual system | +| `responsive.css` | Interactive diagrams and Full HD, 4K, tablet, and mobile adaptations | +| `app.js` | Interactions, state, and Portuguese translations | +| `scripts/verify.mjs` | Content and interaction contract checks | +| `docs/references/` | Primary documentation and additional reading | + +The English HTML is the fallback when JavaScript is unavailable. Portuguese +copy is applied by `app.js`; the language preference is stored in +`localStorage`, and the document language changes to `pt-BR`. + +## Normal edit and publish workflow + +```mermaid +flowchart LR + E[Edit main] --> V[npm run verify] + V --> C[Commit] + C --> M[Push main] + M --> P[Fast-forward pages] + P --> S[Gitea Pages Server] + S --> L[Live URL] +``` + +### 1. Start from current `main` + +```bash +cd /home/marcos/Projects/ai-for-dummies +git switch main +git pull --ff-only +git status --short --branch +``` + +Do not overwrite unrelated local changes. The untracked +`scripts/inspect.py` and `scripts/__pycache__/` are local visual-test artifacts +and are intentionally not part of the published site. + +### 2. Preview locally + +```bash +python3 -m http.server 4173 +``` + +Open [http://localhost:4173](http://localhost:4173). Check English and +Portuguese, keyboard focus, the interactive panels, and at least one desktop +and one mobile viewport. + +### 3. Verify before committing + +```bash +npm run verify +node --check app.js +git diff --check +``` + +Expected project verifier output: + +```text +content verification passed +interaction verification passed +standalone verification passed +``` + +### 4. Commit and push the source branch + +```bash +git add README.md app.js index.html styles.css responsive.css scripts/verify.mjs docs/ +git commit -m "feat: describe the change" +git push origin main +``` + +Stage only files that belong to the change. Review `git status --short` before +committing. + +### 5. Fast-forward the published branch + +Use a temporary worktree so the current checkout stays on `main`: + +```bash +git worktree add /tmp/ai-for-dummies-pages pages +git -C /tmp/ai-for-dummies-pages merge --ff-only main +git -C /tmp/ai-for-dummies-pages push origin pages +git worktree remove /tmp/ai-for-dummies-pages +``` + +The `pages` branch should represent the exact published source. Avoid editing +it directly and avoid force-pushing it. + +### 6. Verify the deployment + +```bash +curl -I https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/ +``` + +If the edge still shows an older page, retry with the current commit as a +cache-busting query: + +```bash +git rev-parse --short HEAD +curl -I "https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/?v=COMMIT" +``` + +The correct URL pattern is **owner subdomain + repository path**: + +```text +https://netcracker.pages.marcospaulo.dev.br/ai-for-dummies/ +``` + +`https://ai-for-dummies.netcracker.pages...` is the wrong hostname and can +produce `ERR_SSL_PROTOCOL_ERROR` because it does not match the wildcard TLS +certificate. + +## Adding or changing a presentation section + +1. Add semantic HTML and stable `data-*` hooks in `index.html`. +2. Put interactive content in a data object inside `app.js`. +3. Add one focused render function and bind its controls once. +4. Add Portuguese static copy to `translations.pt` and dynamic copy to the + relevant interaction data. +5. Add responsive CSS, visible keyboard focus, and reduced-motion behavior. +6. Extend `scripts/verify.mjs` with structural tokens that would disappear if + the feature were accidentally removed. +7. Test English, Portuguese, Full HD, 4K, and mobile layouts. + +Keep English as the source HTML. Do not duplicate the whole site into separate +language endpoints unless the architecture changes to server-side routing. + +## The agent workflow taught by the presentation + +```mermaid +flowchart TD + H[Human intent and boundaries] --> O[Strong orchestrator] + O --> B1[Bounded UI worker] + O --> B2[Bounded test worker] + O --> B3[Bounded docs worker] + B1 --> R[Independent review] + B2 --> R + B3 --> R + R --> E[Evidence and integration] + E --> H +``` + +Use a strong model where ambiguity dominates: repository inspection, +architecture, decomposition, risk analysis, and review. Use faster or cheaper +models for bounded implementation only after the brief defines the goal, +files, constraints, and checks. + +Every worker should return: + +- changed files and a concise diff summary; +- checks executed and their results; +- remaining risk, uncertainty, or blocked work; +- no unrelated edits. + +Parallelism helps only when tasks are genuinely independent. More agents add +coordination cost, context cost, and integration risk. + +## Worktree-per-worker model + +A Git branch isolates history; a Git worktree also isolates the active files +and index. Give each editing agent one task, one branch, and one worktree. + +```bash +git worktree add ../task-ui -b agent/ui +git worktree add ../task-tests -b agent/tests +git worktree add ../task-docs -b agent/docs +git worktree list +``` + +Recommended lifecycle: + +1. Create the task branch and worktree. +2. Give the worker a bounded brief and acceptance checks. +3. Let the worker edit and verify only inside its worktree. +4. Review `git diff main...agent/name` from fresh context. +5. Merge, request changes, or discard. +6. Remove the finished worktree with `git worktree remove PATH`. + +Worktrees prevent agents from changing the same checkout underneath each +other. They do not eliminate semantic merge conflicts; task ownership and +review still matter. + +## What a skill is + +A skill is a reusable procedure that changes how an agent makes decisions. It +is not magical memory and does not replace a task brief or acceptance criteria. + +```text +skill-name/ +├── SKILL.md required: name, description, workflow, constraints +├── agents/openai.yaml optional: UI metadata and invocation policy +├── scripts/ optional: deterministic repeated operations +├── references/ optional: conditional facts and detailed guidance +└── assets/ optional: templates or files copied into output +``` + +Progressive disclosure keeps context light: + +1. **Name and description** are visible during selection. +2. **SKILL.md** loads when the skill applies. +3. **References, scripts, and assets** load only when the workflow needs them. + +Do not create empty resource directories. Every file should have a real +consumer and should improve a decision or repeatable operation. + +## Skill-creation workflow + +### 1. Observe repeated friction + +Collect realistic requests. Identify a non-obvious decision that agents keep +rediscovering or getting wrong. A one-off project fact usually belongs in +project documentation, not a global skill. + +### 2. Define discovery + +Choose a lowercase, action-oriented name. Write a concise description stating +what the skill does and when it applies. Include a boundary only when it stops +likely false activation. + +```yaml +--- +name: review-ui +description: Review frontend changes for focus, responsive layout, and reduced-motion behavior. +--- +``` + +### 3. Choose the smallest anatomy + +- Put shared workflow and constraints in `SKILL.md`. +- Add `scripts/` when deterministic execution prevents repeated reimplementation. +- Add `references/` for details needed only in certain modes. +- Add `assets/` for templates or generated-output inputs. +- Add `agents/openai.yaml` only when UI metadata or invocation policy is useful. + +### 4. Write decision-changing guidance + +Assume the agent is already capable. Include desired outcome, non-obvious +constraints, routing decisions, stopping conditions, and evidence expectations. +Remove generic advice, duplicated manuals, and speculative rules. + +### 5. Validate and iterate + +```bash +python3 /home/marcos/.codex/skills/.system/skill-creator/scripts/quick_validate.py /path/to/skill +``` + +Structural validation checks package shape and frontmatter. It does not prove +the skill makes good decisions. Also run every new script and test realistic +prompts. After real failures, sharpen the narrowest relevant rule instead of +accumulating universal instructions. + +## Common skills and when to use them + +| Skill | Use it for | Core rule | Avoid when | +| :--- | :--- | :--- | :--- | +| `ponytail-lite` | Requests inviting unnecessary frameworks or abstractions | Stop at the first sufficient solution: reuse, standard library, native platform, existing dependency, then minimum new code | Simplification would remove validation, security, accessibility, or real edge cases | +| `caveman` | Routine status, handoffs, and technical summaries | Put signal first and remove filler | Security warnings, irreversible actions, or sequences where terse wording can be misread | +| `unlazy` | Substantial builds, audits, and parallel work | Define observable gates and finish against evidence | Trivial edits or factual answers | +| `research` | APIs, standards, current behavior, and architecture facts | Trace claims to primary sources and save cited findings | The answer is already stable and locally proven | +| `diagnosing-bugs` | Hard bugs, flakes, and regressions | Build a fast red-capable feedback loop before theorizing | Simple known fixes with an existing regression test | +| `code-review` | Branch or PR review | Check repository standards and original specification as separate axes | No comparison point or review request exists | +| `token-saver` | Verbose tests, builds, logs, and Git output | Preserve signal and retain full failure output for recovery | Exact raw wording or full diff context is required | +| `webapp-testing` | Frontend interaction and responsive verification | Drive the real UI and assert on DOM, console, and screenshots | Static structure checks are already decisive | + +Useful compositions: + +- **Large feature:** `unlazy` → `ponytail-lite` → implementation → `code-review`. +- **Hard regression:** `diagnosing-bugs` → fix → `code-review` → `caveman` handoff. +- **Documentation with unstable facts:** `research` → writing → cited verification. +- **Interactive presentation:** `frontend-design` → `webapp-testing` → responsive evidence. + +## Troubleshooting + +| Symptom | Check | Fix | +| :--- | :--- | :--- | +| Live page is old | Compare `main`, `pages`, and remote SHAs | Fast-forward and push `pages`; retry with `?v=COMMIT` | +| `ERR_SSL_PROTOCOL_ERROR` | Confirm the hostname | Use `netcracker.pages.marcospaulo.dev.br/ai-for-dummies/` | +| Portuguese copy is missing | Inspect `translations.pt` and dynamic interaction data | Add both static and dynamic translations; reload after clearing saved language if needed | +| New control does nothing | Check `data-*` hook, event binding, and render function | Add the hook to `scripts/verify.mjs`; run `node --check app.js` | +| Desktop works, mobile breaks | Inspect the section below 800 px and 600 px | Add an explicit stacking rule and preserve focus visibility | +| Worktree creation says branch is checked out | Run `git worktree list` | Reuse or remove the existing worktree; do not force it | +| Pages push is rejected | Fetch and inspect remote branch state | Reconcile normally; never force-push without an explicit recovery decision | + +## Safe rollback + +Prefer a normal revert so history and the `pages` branch remain fast-forwardable: + +```bash +git switch main +git revert BAD_COMMIT +git push origin main +git worktree add /tmp/ai-for-dummies-pages pages +git -C /tmp/ai-for-dummies-pages merge --ff-only main +git -C /tmp/ai-for-dummies-pages push origin pages +git worktree remove /tmp/ai-for-dummies-pages +``` + +Verify the live URL after rollback. Do not use `reset --hard` or force-push for +ordinary content recovery. + +## Completion checklist + +- [ ] English content is complete without JavaScript. +- [ ] Portuguese static and dynamic copy is complete. +- [ ] Mouse and keyboard interactions work. +- [ ] Full HD, 4K, and mobile layouts remain readable. +- [ ] `npm run verify`, `node --check app.js`, and `git diff --check` pass. +- [ ] `main` is pushed. +- [ ] `pages` fast-forwards to the same commit. +- [ ] Live endpoint returns HTTP 200 and contains the new section. +- [ ] Research links and this SilverBullet guide are updated when the workflow changes. + +## Resumo rápido em português + +Edite sempre em `main`, rode as verificações, faça commit e push, depois avance +`pages` por fast-forward usando um worktree temporário. O servidor externo do +Gitea Pages publica diretamente essa branch. Use o endereço com +`netcracker.pages.../ai-for-dummies/`; o formato inverso quebra o TLS. + +Para agentes: modelo forte planeja e revisa; workers delimitados implementam em +worktrees separados; evidências voltam ao orquestrador. Para skills: capture +uma decisão repetida, defina um gatilho preciso, crie apenas os recursos úteis, +escreva orientação que muda decisões e valide estrutura **e** comportamento.