Engineering process
How VexaScript uses journals, tasks, and Codex skills
VexaScript added engineering journals in commit cf5b329b on June 20, 2026.
The repository later added local OpenAI Codex skills under .codex/skills.
These files have different purposes. Journals record investigations. Tasks track work that still needs to be done. Skills describe a repeatable way to do that work.
What a journal records
A release note says what changed. A journal also records the original problem, the tests and commands used to reproduce it, ideas that failed, and the final cause.
| Journal content | Why it helps |
|---|---|
| Original command and error | Makes the problem reproducible |
| Timings, stack traces, or generated code | Shows where the failure happened |
| Failed ideas | Prevents the same dead end next time |
| Root cause | Makes the lesson useful outside one bug |
| Regression test | Keeps the fix executable |
| Remaining work | Separates a partial fix from a completed one |
Compiler bugs often cross several systems. A Monaco error may depend on the virtual filesystem and LSP session, not only the parser. A native C++ crash may come from code generated by an earlier compiler generation. The journal keeps that full sequence.
What a repository skill contains
A Codex skill is a directory with a SKILL.md file. Its description says when
to use it. Its instructions list the evidence to collect, files to update, and
checks to run.
| One-time prompt | Repository skill |
|---|---|
| Exists in one conversation | Stored under .codex/skills |
| Must be repeated | Can trigger for matching work |
| Project details are rebuilt each time | Paths and commands are versioned with the code |
| Validation may be informal | Tests and artifacts can be required |
A skill does not replace engineering judgment. It prevents important project rules from being forgotten during a repeated workflow.
How journals become tasks and skills
problem
-> journal with evidence and failed attempts
-> task with acceptance criteria
-> implementation and tests
-> completed task record
-> skill update when the method should be reused
The journal ingestion workflow moves fully processed notes to
docs/journal/processed/. It does not delete them. This keeps the evidence
available while making the active journal directory easier to review.
Validation rules
Repository skills include the checks required for their type of work. Compiler
changes run focused tests during development, followed by the full pnpm test
suite and the CLI fixture. Website changes also require a production build and
a real browser check.
The blog-writing skill requires Git dates and commits for historical claims. It also requires real benchmark data, clear limits, and browser validation. It now requires short, direct headings and plain language.
Using journals to write technical articles
Git shows the final change and date, but it usually does not explain why an approach was rejected. Journals keep that information. Current code and tests show whether the behavior still exists.
| Question | Best source |
|---|---|
| What happened and in what order? | Engineering journal |
| Which commit introduced it? | Git history |
| What was measured? | Recorded benchmark command and environment |
| What works now? | Current code and tests |
| What remains unsupported? | Journal follow-up and active tasks |
The system is useful when a repeated problem takes less time to understand and fix. The number of Markdown files is not the goal. The goal is to keep evidence and turn it into a reusable, tested procedure.