diff --git a/docs/ai-prompts.md b/docs/ai-prompts.md index 2b955cb..afff6c5 100644 --- a/docs/ai-prompts.md +++ b/docs/ai-prompts.md @@ -21,3 +21,8 @@ Store only the user prompt and a short result summary. - prompt summary: Introduce a mandatory AI logging system by updating `instructions-agent.md` and adding repository logs for AI work entries and prompt summaries. - result summary: Added enforceable AI logging rules to `instructions-agent.md`, created `docs/ai-worklog.md` and `docs/ai-prompts.md`, and established a traceable workflow for recording significant AI-assisted tasks. + +## 2026-03-15 + +- prompt summary: Introduce a standard AI log entry format in `instructions-agent.md` and record the change in the repository AI logs. +- result summary: Added a standardized `AI BUILD ENTRY` and `AI PLAN ENTRY` format, improved consistency expectations for AI logs, and updated the log files to reflect the new format. diff --git a/docs/ai-worklog.md b/docs/ai-worklog.md index 5e58ef9..61f3561 100644 --- a/docs/ai-worklog.md +++ b/docs/ai-worklog.md @@ -31,3 +31,27 @@ Entries must be concise and chronological. - validation: not run - result: The repository now defines mandatory AI logging in `instructions-agent.md` and includes dedicated log files for AI work history and prompt summaries. - open issues: None. + +### AI BUILD ENTRY +Date: 2026-03-15 +Task: build +Objective: Record the introduction of the standard AI log entry format and improve AI logging consistency. + +Files Modified: +- `instructions-agent.md` +- `docs/ai-worklog.md` +- `docs/ai-prompts.md` + +Key Decisions: +- Add a dedicated "Standard AI Log Entry Format" section to define `AI BUILD ENTRY` and `AI PLAN ENTRY` blocks. +- Use the new standardized format for this worklog update to establish the pattern in the repository logs. + +Validation: +- make fix (passed) +- make quality (passed) + +Result: +- The repository now documents a standard AI log entry format and uses it to improve consistency of AI-assisted development logs. + +Open Issues: +- None. diff --git a/instructions-agent.md b/instructions-agent.md index 64df783..40e186a 100644 --- a/instructions-agent.md +++ b/instructions-agent.md @@ -116,6 +116,11 @@ Each worklog entry must include: - result - unresolved issues, if any +Validation logging rule: +- If validation commands such as `make fix`, `make quality`, `pytest`, or other checks are executed during the task, the worklog entry must record them explicitly. +- The value `validation: not run` may only be used if no validation commands were executed. +- The worklog entry must reflect the actual commands run during the task. + Each prompt log entry must include: - date - task type (`plan` or `build`) @@ -128,3 +133,57 @@ Rules: - Store only concise user-facing summaries. - Keep entries chronological. - Even small but meaningful tasks must be logged. + +## Standard AI Log Entry Format + +To ensure consistency and readability of long AI-assisted development histories, all log entries must follow a standardized block format. + +Agents must write log entries using the following structure. + +Example for build tasks: + +### AI BUILD ENTRY +Date: YYYY-MM-DD +Task: build +Objective: short description of the task + +Files Modified: +- file/path/example.py +- another/file.md + +Key Decisions: +- short bullet explaining important choices + +Validation: +- make fix (passed) +- make quality (passed) + +Result: +- short description of what changed or was achieved + +Open Issues: +- optional list of unresolved problems + +Example for plan tasks: + +### AI PLAN ENTRY +Date: YYYY-MM-DD +Task: plan +Objective: short description of planning objective + +Files Inspected: +- src/app/example.py +- specs/example_spec.md + +Proposed Changes: +- summary of planned changes + +Notes: +- optional relevant observations + +Rules: +- Always use these headers exactly (`AI BUILD ENTRY` or `AI PLAN ENTRY`). +- Keep entries concise and structured. +- Do not include chain-of-thought reasoning. +- Use bullet points when possible. +- This format must be used when updating `docs/ai-worklog.md`.