Imported from umbranian0/BTCForecasting-ML (AGENTS.md). Install upstream with npx skills add umbranian0/BTCForecasting-ML. Copyright stays with the author.

AGENTS.md

Mission

This repository is a Codex-enabled workspace for completing and revising a Master's dissertation in English on Forecasting Bitcoin Prices Using Machine Learning.

The assistant must optimise for:

• academic defensibility;
• methodological rigour;
• reproducible experimentation;
• leakage-safe forecasting design;
• clear dissertation-quality writing; and
• faithful implementation of the revision v1 and revision v2 documents.

Authoritative source hierarchy

When sources disagree, use the following order of authority.

1. Current dissertation submission artifact
   • Vasile_Timotin_Mestrado_IPSantarem_versao_20_05_2025_v4.4.docx
2. Current consolidated revision guidance
   • output/doc/revision_master_checklist.md
   • output/doc/revision_v2_consolidated_action_points.md
   • output/doc/revision_v2_thesis_action_points.md
   • output/doc/relatorio_revisao_dissertacao_v2.md
   • output/doc/v4_4_review_action_points.md
   • output/doc/v4_3_review_validation.md
3. Original academic review (revision v1)
   • relatorio_revisao_dissertacao.pdf
4. Editable text and bibliography sources
   • chapters/*.tex
   • references.bib
   • dissertation_from_docx.md
5. Supporting scripts and generated artefacts
   • scripts/*.py
   • output/doc/*.md
   • output/doc/*.docx

Important repository reality

The current .docx manuscript and the LaTeX chapter files are not fully synchronised.

Therefore:

• never assume that changing chapters/*.tex updates the .docx manuscript;
• never assume that the .docx wording is already reflected in the LaTeX sources;
• always state explicitly which artefact is being edited: .docx, .tex, .md, bibliography, or scripts.

Unless the user explicitly requests otherwise, use this default working rule:

• use output/doc/*.md and chapters/*.tex for traceable drafting and revision planning;
• treat the .docx as the final submission artefact that may require manual Word-level finishing for fields, captions, and front matter.

Non-negotiable research and writing rules

The assistant must always:

• write in formal academic English unless a Portuguese artefact is explicitly requested;
• avoid informal tone, filler, and marketing language;
• never fabricate results, references, DOIs, page numbers, tables, or experimental outcomes;
• distinguish clearly between price forecasting, return forecasting, and directional classification;
• prioritise out-of-sample evidence over in-sample fit;
• treat Bitcoin as a non-stationary, volatile, and regime-dependent time series;
• discuss overfitting, structural breaks, leakage risk, and validation design whenever relevant;
• prevent temporal leakage in all feature engineering, preprocessing, model selection, and evaluation steps;
• frame practical usefulness cautiously, distinguishing statistical accuracy from economic profitability after costs.

Required methodological scope

All analysis and drafting should remain consistent with the dissertation's intended scope:

• statistical baselines: naive, seasonal naive, ARIMA;
• machine learning models: penalised regression, Random Forest, LightGBM, CatBoost;
• deep learning models: LSTM, GRU, Transformer-based models;
• hybrid/regime-aware models: HMM, HMM plus LSTM, or similar justified combinations;
• evaluation: walk-forward validation, purge gaps, leakage prevention, horizons of 1 hour, 6 hours, and 24 hours.

Revision priorities that must govern all work

The current unresolved priorities from revision v1 and v2 are:

1. formalise the Introduction with one general objective, numbered specific objectives, one explicit research question, and one delimitation paragraph;
2. fix the front matter in the Word manuscript, especially the List of Figures / broken bookmark issues;
3. unify and clean the bibliography system, including duplicate removal and citation-reference consistency;
4. strengthen the limitations framing on transaction costs, incomplete exogenous coverage, practical utility, and limited LSTM tuning;
5. add a clear justification for the 1-hour horizon as the most demanding and noisy horizon;
6. improve recent literature coverage on Transformers, regime-aware models, and strict-validation cryptocurrency forecasting;
7. reframe the dissertation more cautiously as a leakage-aware benchmarking study rather than proof of robust trading utility or full multimodal superiority.

Before starting a substantive rewrite, check the relevant revision documents.

Agent topology for Codex

Codex may work with multiple agents, but each agent must have a clear and non-overlapping responsibility.

1. Coordinator agent

Use as the main agent for:

• task decomposition;
• deciding which artefact is authoritative for the current task;
• integrating outputs from subagents;
• ensuring consistency with revision v1 and v2.

The coordinator should not delegate the immediate critical-path task if the next action depends on it.

2. Revision explorer

Use an explorer subagent for:

• reading review documents;
• mapping unresolved action points;
• locating evidence in the repository;
• identifying whether an issue is already resolved, partially resolved, or still open.

Write scope:

• preferably none;
• at most output/doc/*.md notes.

3. Chapter revision worker

Use a worker subagent for chapter-level text revision.

Typical ownership examples:

• chapters/introduction.tex and related staging notes;
• chapters/literature_review.tex and related staging notes;
• chapters/methodology.tex, chapters/results.tex, chapters/discussion.tex, or chapters/conclusion.tex.

Rules:

• one worker owns one chapter group at a time;
• do not let two workers edit the same file set simultaneously;
• preserve academic tone and the review priorities listed above.

4. Bibliography and APA worker

Use a worker or explorer for:

• citation-reference audits;
• deduplication checks;
• APA 7 consistency checks;
• identifying missing, unused, or weak references.

Write scope:

• references.bib
• output/doc/bibliography_*.md
• optional helper scripts under scripts/

5. Methodology and results validator

Use an explorer or worker for:

• leakage checks;
• validation protocol checking;
• horizon justification;
• clarifying what was actually executed versus what the broader framework supports.

Write scope:

• methodology/results/discussion chapter files;
• supporting notes in output/doc/.

6. Document finaliser

Use a worker for:

• Word-facing support scripts;
• revision artefact generation;
• front-matter notes;
• figure/table/caption checklists.

Write scope:

• scripts/
• output/doc/
• .vscode/
• configuration files only.

Multi-agent collaboration rules

When using subagents:

• assign disjoint file ownership;
• prefer explorer agents for read-only repository questions;
• prefer worker agents for bounded, file-specific revisions;
• never allow two workers to rewrite the same chapter or bibliography file concurrently;
• integrate results carefully rather than overwriting another agent's work.

Standard workflow for thesis-improvement tasks

For any substantial revision request, follow this sequence:

1. identify the artefact to change (.docx, .tex, .md, bibliography, or script);
2. read the applicable revision source(s);
3. restate the target change in academically precise language;
4. make the revision with leakage-safe, evidence-aware wording;
5. if citations changed, run or update a bibliography consistency check;
6. record what changed and what remains open.

Artefact-specific instructions

Word manuscript (*.docx)

• Treat the current .docx as the final delivery artefact.
• Some front-matter defects, bookmark errors, figure fields, and table-of-figures issues may require manual Microsoft Word refresh or repair.
• Codex may prepare supporting notes, scripts, or replacement text, but should not claim that Word field issues are fully fixed unless verified.

LaTeX chapter sources (chapters/*.tex)

• These files are suitable for structured text editing inside Visual Studio.
• Because they lag behind the .docx, use them for clean drafting and staging, not as proof that the final .docx already matches them.

Bibliography (references.bib)

• references.bib is the editable bibliography source for source-controlled work.
• Keep APA 7 consistency in mind, but never invent missing metadata.
• When uncertain, flag the incomplete entry rather than fabricating it.

Revision notes (output/doc/*.md)

• Use output/doc/ for staging notes, checklists, chapter rewrites, and audit reports.
• Keep filenames stable and descriptive.

Environment and Visual Studio expectations

• The intended thesis environment is defined in environment.yml.
• The repository currently contains inconsistent local interpreters; verify the active Python interpreter before running notebooks or scripts.
• Visual Studio / VS Code search should ignore .conda and agent_sandbox to avoid noise and performance issues.

Definition of done for a revision task

A task is only complete when all of the following are true:

• the revised text is academically defensible;
• the change directly addresses the relevant v1/v2 review point;
• the wording does not overclaim predictive power or practical tradability;
• citations and references remain internally consistent;
• the assistant states clearly which artefact was changed and which issues remain manual or unresolved.