2237 lines
176 KiB
HTML
2237 lines
176 KiB
HTML
<!DOCTYPE html>
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="de" xml:lang="de"><head>
|
||
|
||
<meta charset="utf-8">
|
||
<meta name="generator" content="quarto-1.7.23">
|
||
|
||
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
|
||
|
||
<meta name="description" content="A real Field Report out of the trences of AI-assisted coding with its ups and downs.">
|
||
|
||
<title>Field Report: Coding in the Age of AI with Cursor – Nicole Dresselhaus</title>
|
||
<style>
|
||
code{white-space: pre-wrap;}
|
||
span.smallcaps{font-variant: small-caps;}
|
||
div.columns{display: flex; gap: min(4vw, 1.5em);}
|
||
div.column{flex: auto; overflow-x: auto;}
|
||
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
|
||
ul.task-list{list-style: none;}
|
||
ul.task-list li input[type="checkbox"] {
|
||
width: 0.8em;
|
||
margin: 0 0.8em 0.2em -1em; /* quarto-specific, see https://github.com/quarto-dev/quarto-cli/issues/4556 */
|
||
vertical-align: middle;
|
||
}
|
||
/* CSS for syntax highlighting */
|
||
html { -webkit-text-size-adjust: 100%; }
|
||
pre > code.sourceCode { white-space: pre; position: relative; }
|
||
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
|
||
pre > code.sourceCode > span:empty { height: 1.2em; }
|
||
.sourceCode { overflow: visible; }
|
||
code.sourceCode > span { color: inherit; text-decoration: inherit; }
|
||
div.sourceCode { margin: 1em 0; }
|
||
pre.sourceCode { margin: 0; }
|
||
@media screen {
|
||
div.sourceCode { overflow: auto; }
|
||
}
|
||
@media print {
|
||
pre > code.sourceCode { white-space: pre-wrap; }
|
||
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
|
||
}
|
||
pre.numberSource code
|
||
{ counter-reset: source-line 0; }
|
||
pre.numberSource code > span
|
||
{ position: relative; left: -4em; counter-increment: source-line; }
|
||
pre.numberSource code > span > a:first-child::before
|
||
{ content: counter(source-line);
|
||
position: relative; left: -1em; text-align: right; vertical-align: baseline;
|
||
border: none; display: inline-block;
|
||
-webkit-touch-callout: none; -webkit-user-select: none;
|
||
-khtml-user-select: none; -moz-user-select: none;
|
||
-ms-user-select: none; user-select: none;
|
||
padding: 0 4px; width: 4em;
|
||
}
|
||
pre.numberSource { margin-left: 3em; padding-left: 4px; }
|
||
div.sourceCode
|
||
{ }
|
||
@media screen {
|
||
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
|
||
}
|
||
/* CSS for citations */
|
||
div.csl-bib-body { }
|
||
div.csl-entry {
|
||
clear: both;
|
||
margin-bottom: 0em;
|
||
}
|
||
.hanging-indent div.csl-entry {
|
||
margin-left:2em;
|
||
text-indent:-2em;
|
||
}
|
||
div.csl-left-margin {
|
||
min-width:2em;
|
||
float:left;
|
||
}
|
||
div.csl-right-inline {
|
||
margin-left:2em;
|
||
padding-left:1em;
|
||
}
|
||
div.csl-indent {
|
||
margin-left: 2em;
|
||
}</style>
|
||
|
||
|
||
<script src="../site_libs/quarto-nav/quarto-nav.js"></script>
|
||
<script src="../site_libs/quarto-nav/headroom.min.js"></script>
|
||
<script src="../site_libs/clipboard/clipboard.min.js"></script>
|
||
<script src="../site_libs/quarto-search/autocomplete.umd.js"></script>
|
||
<script src="../site_libs/quarto-search/fuse.min.js"></script>
|
||
<script src="../site_libs/quarto-search/quarto-search.js"></script>
|
||
<meta name="quarto:offset" content="../">
|
||
<script src="../site_libs/quarto-html/quarto.js" type="module"></script>
|
||
<script src="../site_libs/quarto-html/tabsets/tabsets.js" type="module"></script>
|
||
<script src="../site_libs/quarto-html/popper.min.js"></script>
|
||
<script src="../site_libs/quarto-html/tippy.umd.min.js"></script>
|
||
<script src="../site_libs/quarto-html/anchor.min.js"></script>
|
||
<link href="../site_libs/quarto-html/tippy.css" rel="stylesheet">
|
||
<link href="../site_libs/quarto-html/quarto-syntax-highlighting-dark-2c84ecb840a13f4c7993f9e5648f0c14.css" rel="stylesheet" class="quarto-color-scheme quarto-color-alternate" id="quarto-text-highlighting-styles">
|
||
<link href="../site_libs/quarto-html/quarto-syntax-highlighting-6cf5824034cebd0380a5b9c74c43f006.css" rel="stylesheet" class="quarto-color-scheme" id="quarto-text-highlighting-styles">
|
||
<script src="../site_libs/bootstrap/bootstrap.min.js"></script>
|
||
<link href="../site_libs/bootstrap/bootstrap-icons.css" rel="stylesheet">
|
||
<link href="../site_libs/bootstrap/bootstrap-ec71cb1e120c0dd41819aca960e74e38.min.css" rel="stylesheet" append-hash="true" class="quarto-color-scheme" id="quarto-bootstrap" data-mode="light">
|
||
<link href="../site_libs/bootstrap/bootstrap-dark-716ed94a23403968eaa6fe981e0cbf91.min.css" rel="stylesheet" append-hash="true" class="quarto-color-scheme quarto-color-alternate" id="quarto-bootstrap" data-mode="dark">
|
||
<link href="../site_libs/bootstrap/bootstrap-ec71cb1e120c0dd41819aca960e74e38.min.css" rel="stylesheet" append-hash="true" class="quarto-color-scheme-extra" id="quarto-bootstrap" data-mode="light">
|
||
<script src="../site_libs/quarto-contrib/glightbox/glightbox.min.js"></script>
|
||
<link href="../site_libs/quarto-contrib/glightbox/glightbox.min.css" rel="stylesheet">
|
||
<link href="../site_libs/quarto-contrib/glightbox/lightbox.css" rel="stylesheet">
|
||
<script id="quarto-search-options" type="application/json">{
|
||
"location": "navbar",
|
||
"copy-button": false,
|
||
"collapse-after": 3,
|
||
"panel-placement": "end",
|
||
"type": "overlay",
|
||
"limit": 50,
|
||
"keyboard-shortcut": [
|
||
"f",
|
||
"/",
|
||
"s"
|
||
],
|
||
"show-item-context": false,
|
||
"language": {
|
||
"search-no-results-text": "Keine Treffer",
|
||
"search-matching-documents-text": "Treffer",
|
||
"search-copy-link-title": "Link in die Suche kopieren",
|
||
"search-hide-matches-text": "Zusätzliche Treffer verbergen",
|
||
"search-more-match-text": "weitere Treffer in diesem Dokument",
|
||
"search-more-matches-text": "weitere Treffer in diesem Dokument",
|
||
"search-clear-button-title": "Zurücksetzen",
|
||
"search-text-placeholder": "",
|
||
"search-detached-cancel-button-title": "Abbrechen",
|
||
"search-submit-button-title": "Abschicken",
|
||
"search-label": "Suchen"
|
||
}
|
||
}</script>
|
||
|
||
|
||
<meta property="og:title" content="Field Report: Coding in the Age of AI with Cursor – Nicole Dresselhaus">
|
||
<meta property="og:description" content="A real Field Report out of the trences of AI-assisted coding with its ups and downs.">
|
||
<meta property="og:image" content="https://drezil.de/thumbs/writing_coding-age-ai.png">
|
||
<meta property="og:site_name" content="Nicole Dresselhaus">
|
||
<meta property="og:image:height" content="400">
|
||
<meta property="og:image:width" content="600">
|
||
<meta name="citation_title" content="Field Report: Coding in the Age of AI with Cursor">
|
||
<meta name="citation_abstract" content="This report presents practical methodologies and best practices for developing software using Cursor, an AI-assisted IDE. The paper details a structured workflow that emphasizes specification-driven development, comprehensive documentation practices, and systematic task management to maintain quality control when working with language models. Through detailed examples and rule configurations, it demonstrates how to leverage AI capabilities while mitigating common pitfalls such as redundant code generation and context limitations. The methodology presented includes comprehensive PRD (Product Requirement Document) creation, specification adherence checks, and task breakdown systems that ensure alignment between human intent and AI execution. This guide serves as a practical reference for developers seeking to effectively integrate AI tools into their software development workflow while maintaining project integrity and scalability.
|
||
">
|
||
<meta name="citation_author" content="Nicole Dresselhaus">
|
||
<meta name="citation_publication_date" content="2025-06-26">
|
||
<meta name="citation_cover_date" content="2025-06-26">
|
||
<meta name="citation_year" content="2025">
|
||
<meta name="citation_online_date" content="2025-06-26">
|
||
<meta name="citation_fulltext_html_url" content="https://drezil.de/Writing/coding-age-ai.html">
|
||
<meta name="citation_language" content="de">
|
||
<meta name="citation_reference" content="citation_title=The LLM’s RL Revelation We Didn’t See Coming;,citation_publication_date=2025-06-24;,citation_cover_date=2025-06-24;,citation_year=2025;,citation_fulltext_html_url=https://www.youtube.com/watch?v=z3awgfU4yno;">
|
||
<meta name="citation_reference" content="citation_title=DeepSeek-R1: Incentivizing Reasoning Capability in LLMs via Reinforcement Learning;,citation_abstract=We introduce our first-generation reasoning models, DeepSeek-R1-Zero and DeepSeek-R1. DeepSeek-R1-Zero, a model trained via large-scale reinforcement learning (RL) without supervised fine-tuning (SFT) as a preliminary step, demonstrates remarkable reasoning capabilities. Through RL, DeepSeek-R1-Zero naturally emerges with numerous powerful and intriguing reasoning behaviors. However, it encounters challenges such as poor readability, and language mixing. To address these issues and further enhance reasoning performance, we introduce DeepSeek-R1, which incorporates multi-stage training and cold-start data before RL. DeepSeek-R1 achieves performance comparable to OpenAI-o1-1217 on reasoning tasks. To support the research community, we open-source DeepSeek-R1-Zero, DeepSeek-R1, and six dense models (1.5B, 7B, 8B, 14B, 32B, 70B) distilled from DeepSeek-R1 based on Qwen and Llama.;,citation_author=undefined DeepSeek-AI;,citation_author=Daya Guo;,citation_author=Dejian Yang;,citation_author=Haowei Zhang;,citation_author=Junxiao Song;,citation_author=Ruoyu Zhang;,citation_author=Runxin Xu;,citation_author=Qihao Zhu;,citation_author=Shirong Ma;,citation_author=Peiyi Wang;,citation_author=Xiao Bi;,citation_author=Xiaokang Zhang;,citation_author=Xingkai Yu;,citation_author=Yu Wu;,citation_author=Z. F. Wu;,citation_author=Zhibin Gou;,citation_author=Zhihong Shao;,citation_author=Zhuoshu Li;,citation_author=Ziyi Gao;,citation_author=Aixin Liu;,citation_author=Bing Xue;,citation_author=Bingxuan Wang;,citation_author=Bochao Wu;,citation_author=Bei Feng;,citation_author=Chengda Lu;,citation_author=Chenggang Zhao;,citation_author=Chengqi Deng;,citation_author=Chenyu Zhang;,citation_author=Chong Ruan;,citation_author=Damai Dai;,citation_author=Deli Chen;,citation_author=Dongjie Ji;,citation_author=Erhang Li;,citation_author=Fangyun Lin;,citation_author=Fucong Dai;,citation_author=Fuli Luo;,citation_author=Guangbo Hao;,citation_author=Guanting Chen;,citation_author=Guowei Li;,citation_author=H. Zhang;,citation_author=Han Bao;,citation_author=Hanwei Xu;,citation_author=Haocheng Wang;,citation_author=Honghui Ding;,citation_author=Huajian Xin;,citation_author=Huazuo Gao;,citation_author=Hui Qu;,citation_author=Hui Li;,citation_author=Jianzhong Guo;,citation_author=Jiashi Li;,citation_author=Jiawei Wang;,citation_author=Jingchang Chen;,citation_author=Jingyang Yuan;,citation_author=Junjie Qiu;,citation_author=Junlong Li;,citation_author=J. L. Cai;,citation_author=Jiaqi Ni;,citation_author=Jian Liang;,citation_author=Jin Chen;,citation_author=Kai Dong;,citation_author=Kai Hu;,citation_author=Kaige Gao;,citation_author=Kang Guan;,citation_author=Kexin Huang;,citation_author=Kuai Yu;,citation_author=Lean Wang;,citation_author=Lecong Zhang;,citation_author=Liang Zhao;,citation_author=Litong Wang;,citation_author=Liyue Zhang;,citation_author=Lei Xu;,citation_author=Leyi Xia;,citation_author=Mingchuan Zhang;,citation_author=Minghua Zhang;,citation_author=Minghui Tang;,citation_author=Meng Li;,citation_author=Miaojun Wang;,citation_author=Mingming Li;,citation_author=Ning Tian;,citation_author=Panpan Huang;,citation_author=Peng Zhang;,citation_author=Qiancheng Wang;,citation_author=Qinyu Chen;,citation_author=Qiushi Du;,citation_author=Ruiqi Ge;,citation_author=Ruisong Zhang;,citation_author=Ruizhe Pan;,citation_author=Runji Wang;,citation_author=R. J. Chen;,citation_author=R. L. Jin;,citation_author=Ruyi Chen;,citation_author=Shanghao Lu;,citation_author=Shangyan Zhou;,citation_author=Shanhuang Chen;,citation_author=Shengfeng Ye;,citation_author=Shiyu Wang;,citation_author=Shuiping Yu;,citation_author=Shunfeng Zhou;,citation_author=Shuting Pan;,citation_author=S. S. Li;,citation_author=Shuang Zhou;,citation_author=Shaoqing Wu;,citation_author=Shengfeng Ye;,citation_author=Tao Yun;,citation_author=Tian Pei;,citation_author=Tianyu Sun;,citation_author=T. Wang;,citation_author=Wangding Zeng;,citation_author=Wanjia Zhao;,citation_author=Wen Liu;,citation_author=Wenfeng Liang;,citation_author=Wenjun Gao;,citation_author=Wenqin Yu;,citation_author=Wentao Zhang;,citation_author=W. L. Xiao;,citation_author=Wei An;,citation_author=Xiaodong Liu;,citation_author=Xiaohan Wang;,citation_author=Xiaokang Chen;,citation_author=Xiaotao Nie;,citation_author=Xin Cheng;,citation_author=Xin Liu;,citation_author=Xin Xie;,citation_author=Xingchao Liu;,citation_author=Xinyu Yang;,citation_author=Xinyuan Li;,citation_author=Xuecheng Su;,citation_author=Xuheng Lin;,citation_author=X. Q. Li;,citation_author=Xiangyue Jin;,citation_author=Xiaojin Shen;,citation_author=Xiaosha Chen;,citation_author=Xiaowen Sun;,citation_author=Xiaoxiang Wang;,citation_author=Xinnan Song;,citation_author=Xinyi Zhou;,citation_author=Xianzu Wang;,citation_author=Xinxia Shan;,citation_author=Y. K. Li;,citation_author=Y. Q. Wang;,citation_author=Y. X. Wei;,citation_author=Yang Zhang;,citation_author=Yanhong Xu;,citation_author=Yao Li;,citation_author=Yao Zhao;,citation_author=Yaofeng Sun;,citation_author=Yaohui Wang;,citation_author=Yi Yu;,citation_author=Yichao Zhang;,citation_author=Yifan Shi;,citation_author=Yiliang Xiong;,citation_author=Ying He;,citation_author=Yishi Piao;,citation_author=Yisong Wang;,citation_author=Yixuan Tan;,citation_author=Yiyang Ma;,citation_author=Yiyuan Liu;,citation_author=Yongqiang Guo;,citation_author=Yuan Ou;,citation_author=Yuduan Wang;,citation_author=Yue Gong;,citation_author=Yuheng Zou;,citation_author=Yujia He;,citation_author=Yunfan Xiong;,citation_author=Yuxiang Luo;,citation_author=Yuxiang You;,citation_author=Yuxuan Liu;,citation_author=Yuyang Zhou;,citation_author=Y. X. Zhu;,citation_author=Yanhong Xu;,citation_author=Yanping Huang;,citation_author=Yaohui Li;,citation_author=Yi Zheng;,citation_author=Yuchen Zhu;,citation_author=Yunxian Ma;,citation_author=Ying Tang;,citation_author=Yukun Zha;,citation_author=Yuting Yan;,citation_author=Z. Z. Ren;,citation_author=Zehui Ren;,citation_author=Zhangli Sha;,citation_author=Zhe Fu;,citation_author=Zhean Xu;,citation_author=Zhenda Xie;,citation_author=Zhengyan Zhang;,citation_author=Zhewen Hao;,citation_author=Zhicheng Ma;,citation_author=Zhigang Yan;,citation_author=Zhiyu Wu;,citation_author=Zihui Gu;,citation_author=Zijia Zhu;,citation_author=Zijun Liu;,citation_author=Zilin Li;,citation_author=Ziwei Xie;,citation_author=Ziyang Song;,citation_author=Zizheng Pan;,citation_author=Zhen Huang;,citation_author=Zhipeng Xu;,citation_author=Zhongyu Zhang;,citation_author=Zhen Zhang;,citation_publication_date=2025-01-22;,citation_cover_date=2025-01-22;,citation_year=2025;,citation_fulltext_html_url=http://arxiv.org/abs/2501.12948;,citation_doi=10.48550/arXiv.2501.12948;">
|
||
<meta name="citation_reference" content="citation_title=Understanding R1-Zero-Like Training: A Critical Perspective;,citation_abstract=DeepSeek-R1-Zero has shown that reinforcement learning (RL) at scale can directly enhance the reasoning capabilities of LLMs without supervised fine-tuning. In this work, we critically examine R1-Zero-like training by analyzing its two core components: base models and RL. We investigate a wide range of base models, including DeepSeek-V3-Base, to understand how pretraining characteristics influence RL performance. Our analysis reveals that DeepSeek-V3-Base already exhibit ”Aha moment”, while Qwen2.5 base models demonstrate strong reasoning capabilities even without prompt templates, suggesting potential pretraining biases. Additionally, we identify an optimization bias in Group Relative Policy Optimization (GRPO), which artificially increases response length (especially for incorrect outputs) during training. To address this, we introduce Dr. GRPO, an unbiased optimization method that improves token efficiency while maintaining reasoning performance. Leveraging these insights, we present a minimalist R1-Zero recipe that achieves 43.3% accuracy on AIME 2024 with a 7B base model, establishing a new state-of-the-art. Our code is available at https://github.com/sail-sg/understand-r1-zero.;,citation_author=Zichen Liu;,citation_author=Changyu Chen;,citation_author=Wenjun Li;,citation_author=Penghui Qi;,citation_author=Tianyu Pang;,citation_author=Chao Du;,citation_author=Wee Sun Lee;,citation_author=Min Lin;,citation_publication_date=2025-03-26;,citation_cover_date=2025-03-26;,citation_year=2025;,citation_fulltext_html_url=http://arxiv.org/abs/2503.20783;,citation_doi=10.48550/arXiv.2503.20783;">
|
||
<meta name="citation_reference" content="citation_title=Reinforcement Learning Finetunes Small Subnetworks in Large Language Models;,citation_abstract=Reinforcement learning (RL) yields substantial improvements in large language models (LLMs) downstream task performance and alignment with human values. Surprisingly, such large gains result from updating only a small subnetwork comprising just 5 percent to 30 percent of the parameters, with the rest effectively unchanged. We refer to this phenomenon as parameter update sparsity induced by RL. It is observed across all 7 widely used RL algorithms (e.g., PPO, GRPO, DPO) and all 10 LLMs from different families in our experiments. This sparsity is intrinsic and occurs without any explicit sparsity promoting regularizations or architectural constraints. Finetuning the subnetwork alone recovers the test accuracy, and, remarkably, produces a model nearly identical to the one obtained via full finetuning. The subnetworks from different random seeds, training data, and even RL algorithms show substantially greater overlap than expected by chance. Our analysis suggests that this sparsity is not due to updating only a subset of layers, instead, nearly all parameter matrices receive similarly sparse updates. Moreover, the updates to almost all parameter matrices are nearly full-rank, suggesting RL updates a small subset of parameters that nevertheless span almost the full subspaces that the parameter matrices can represent. We conjecture that the this update sparsity can be primarily attributed to training on data that is near the policy distribution, techniques that encourage the policy to remain close to the pretrained model, such as the KL regularization and gradient clipping, have limited impact.;,citation_author=Sagnik Mukherjee;,citation_author=Lifan Yuan;,citation_author=Dilek Hakkani-Tur;,citation_author=Hao Peng;,citation_publication_date=2025-05-16;,citation_cover_date=2025-05-16;,citation_year=2025;,citation_fulltext_html_url=http://arxiv.org/abs/2505.11711;,citation_doi=10.48550/arXiv.2505.11711;">
|
||
<meta name="citation_reference" content="citation_title=Spurious Rewards: Rethinking Training Signals in RLVR;,citation_abstract=We show that reinforcement learning with verifiable rewards (RLVR) can elicit strong mathematical reasoning in certain models even with spurious rewards that have little, no, or even negative correlation with the correct answer. For example, RLVR improves MATH-500 performance for Qwen2.5-Math-7B in absolute points by 21.4% (random reward), 13.8% (format reward), 24.1% (incorrect label), 26.0% (1-shot RL), and 27.1% (majority voting) – nearly matching the 29.1% gained with ground truth rewards. However, the spurious rewards that work for Qwen often fail to yield gains with other model families like Llama3 or OLMo2. In particular, we find code reasoning – thinking in code without actual code execution – to be a distinctive Qwen2.5-Math behavior that becomes significantly more frequent after RLVR, from 65% to over 90%, even with spurious rewards. Overall, we hypothesize that, given the lack of useful reward signal, RLVR must somehow be surfacing useful reasoning representations learned during pretraining, although the exact mechanism remains a topic for future work. We suggest that future RLVR research should possibly be validated on diverse models rather than a single de facto choice, as we show that it is easy to get significant performance gains on Qwen models even with completely spurious reward signals.;,citation_author=Rulin Shao;,citation_author=Shuyue Stella Li;,citation_author=Rui Xin;,citation_author=Scott Geng;,citation_author=Yiping Wang;,citation_author=Sewoong Oh;,citation_author=Simon Shaolei Du;,citation_author=Nathan Lambert;,citation_author=Sewon Min;,citation_author=Ranjay Krishna;,citation_author=Yulia Tsvetkov;,citation_author=Hannaneh Hajishirzi;,citation_author=Pang Wei Koh;,citation_author=Luke Zettlemoyer;,citation_publication_date=2025-06-12;,citation_cover_date=2025-06-12;,citation_year=2025;,citation_fulltext_html_url=http://arxiv.org/abs/2506.10947;,citation_doi=10.48550/arXiv.2506.10947;">
|
||
<meta name="citation_reference" content="citation_title=Does Reinforcement Learning Really Incentivize Reasoning Capacity in LLMs Beyond the Base Model?;,citation_abstract=Reinforcement Learning with Verifiable Rewards (RLVR) has recently demonstrated notable success in enhancing the reasoning performance of large language models (LLMs), particularly on mathematics and programming tasks. Similar to how traditional RL helps agents explore and learn new strategies, RLVR is believed to enable LLMs to continuously self-improve, thus acquiring novel reasoning abilities beyond those of the corresponding base models. In this study we critically examine the current state of RLVR by systematically probing the reasoning capability boundaries of RLVR-trained LLMs across various model families, RL algorithms, and math, coding, and visual reasoning benchmarks, using pass@k at large k values as the evaluation metric. Surprisingly, we find that the current training setup does not elicit fundamentally new reasoning patterns. While RLVR-trained models outperform their base models at small k (e.g., k = 1), the base models achieve a higher pass@k score when k is large. Coverage and perplexity analyses show that the observed reasoning abilities originate from and are bounded by the base model. Treating the base model as an upper bound, our quantitative analysis shows that six popular RLVR algorithms perform similarly and remain far from optimal in leveraging the potential of the base model. By contrast, we find that distillation can introduce new reasoning patterns from the teacher and genuinely expand the model’s reasoning capabilities. Overall, our findings suggest that current RLVR methods have not yet realized the potential of RL to elicit truly novel reasoning abilities in LLMs. This highlights the need for improved RL paradigms, such as continual scaling and multi-turn agent-environment interaction, to unlock this potential.;,citation_author=Yang Yue;,citation_author=Zhiqi Chen;,citation_author=Rui Lu;,citation_author=Andrew Zhao;,citation_author=Zhaokai Wang;,citation_author=Yang Yue;,citation_author=Shiji Song;,citation_author=Gao Huang;,citation_publication_date=2025-05-16;,citation_cover_date=2025-05-16;,citation_year=2025;,citation_fulltext_html_url=http://arxiv.org/abs/2504.13837;,citation_doi=10.48550/arXiv.2504.13837;">
|
||
</head>
|
||
|
||
<body class="nav-sidebar docked nav-fixed slimcontent quarto-light"><script id="quarto-html-before-body" type="application/javascript">
|
||
const toggleBodyColorMode = (bsSheetEl) => {
|
||
const mode = bsSheetEl.getAttribute("data-mode");
|
||
const bodyEl = window.document.querySelector("body");
|
||
if (mode === "dark") {
|
||
bodyEl.classList.add("quarto-dark");
|
||
bodyEl.classList.remove("quarto-light");
|
||
} else {
|
||
bodyEl.classList.add("quarto-light");
|
||
bodyEl.classList.remove("quarto-dark");
|
||
}
|
||
}
|
||
const toggleBodyColorPrimary = () => {
|
||
const bsSheetEl = window.document.querySelector("link#quarto-bootstrap:not([rel=disabled-stylesheet])");
|
||
if (bsSheetEl) {
|
||
toggleBodyColorMode(bsSheetEl);
|
||
}
|
||
}
|
||
window.setColorSchemeToggle = (alternate) => {
|
||
const toggles = window.document.querySelectorAll('.quarto-color-scheme-toggle');
|
||
for (let i=0; i < toggles.length; i++) {
|
||
const toggle = toggles[i];
|
||
if (toggle) {
|
||
if (alternate) {
|
||
toggle.classList.add("alternate");
|
||
} else {
|
||
toggle.classList.remove("alternate");
|
||
}
|
||
}
|
||
}
|
||
};
|
||
const toggleColorMode = (alternate) => {
|
||
// Switch the stylesheets
|
||
const primaryStylesheets = window.document.querySelectorAll('link.quarto-color-scheme:not(.quarto-color-alternate)');
|
||
const alternateStylesheets = window.document.querySelectorAll('link.quarto-color-scheme.quarto-color-alternate');
|
||
manageTransitions('#quarto-margin-sidebar .nav-link', false);
|
||
if (alternate) {
|
||
// note: dark is layered on light, we don't disable primary!
|
||
enableStylesheet(alternateStylesheets);
|
||
for (const sheetNode of alternateStylesheets) {
|
||
if (sheetNode.id === "quarto-bootstrap") {
|
||
toggleBodyColorMode(sheetNode);
|
||
}
|
||
}
|
||
} else {
|
||
disableStylesheet(alternateStylesheets);
|
||
enableStylesheet(primaryStylesheets)
|
||
toggleBodyColorPrimary();
|
||
}
|
||
manageTransitions('#quarto-margin-sidebar .nav-link', true);
|
||
// Switch the toggles
|
||
window.setColorSchemeToggle(alternate)
|
||
// Hack to workaround the fact that safari doesn't
|
||
// properly recolor the scrollbar when toggling (#1455)
|
||
if (navigator.userAgent.indexOf('Safari') > 0 && navigator.userAgent.indexOf('Chrome') == -1) {
|
||
manageTransitions("body", false);
|
||
window.scrollTo(0, 1);
|
||
setTimeout(() => {
|
||
window.scrollTo(0, 0);
|
||
manageTransitions("body", true);
|
||
}, 40);
|
||
}
|
||
}
|
||
const disableStylesheet = (stylesheets) => {
|
||
for (let i=0; i < stylesheets.length; i++) {
|
||
const stylesheet = stylesheets[i];
|
||
stylesheet.rel = 'disabled-stylesheet';
|
||
}
|
||
}
|
||
const enableStylesheet = (stylesheets) => {
|
||
for (let i=0; i < stylesheets.length; i++) {
|
||
const stylesheet = stylesheets[i];
|
||
if(stylesheet.rel !== 'stylesheet') { // for Chrome, which will still FOUC without this check
|
||
stylesheet.rel = 'stylesheet';
|
||
}
|
||
}
|
||
}
|
||
const manageTransitions = (selector, allowTransitions) => {
|
||
const els = window.document.querySelectorAll(selector);
|
||
for (let i=0; i < els.length; i++) {
|
||
const el = els[i];
|
||
if (allowTransitions) {
|
||
el.classList.remove('notransition');
|
||
} else {
|
||
el.classList.add('notransition');
|
||
}
|
||
}
|
||
}
|
||
const isFileUrl = () => {
|
||
return window.location.protocol === 'file:';
|
||
}
|
||
window.hasAlternateSentinel = () => {
|
||
let styleSentinel = getColorSchemeSentinel();
|
||
if (styleSentinel !== null) {
|
||
return styleSentinel === "alternate";
|
||
} else {
|
||
return false;
|
||
}
|
||
}
|
||
const setStyleSentinel = (alternate) => {
|
||
const value = alternate ? "alternate" : "default";
|
||
if (!isFileUrl()) {
|
||
window.localStorage.setItem("quarto-color-scheme", value);
|
||
} else {
|
||
localAlternateSentinel = value;
|
||
}
|
||
}
|
||
const getColorSchemeSentinel = () => {
|
||
if (!isFileUrl()) {
|
||
const storageValue = window.localStorage.getItem("quarto-color-scheme");
|
||
return storageValue != null ? storageValue : localAlternateSentinel;
|
||
} else {
|
||
return localAlternateSentinel;
|
||
}
|
||
}
|
||
const toggleGiscusIfUsed = (isAlternate, darkModeDefault) => {
|
||
const baseTheme = document.querySelector('#giscus-base-theme')?.value ?? 'light';
|
||
const alternateTheme = document.querySelector('#giscus-alt-theme')?.value ?? 'dark';
|
||
let newTheme = '';
|
||
if(darkModeDefault) {
|
||
newTheme = isAlternate ? baseTheme : alternateTheme;
|
||
} else {
|
||
newTheme = isAlternate ? alternateTheme : baseTheme;
|
||
}
|
||
const changeGiscusTheme = () => {
|
||
// From: https://github.com/giscus/giscus/issues/336
|
||
const sendMessage = (message) => {
|
||
const iframe = document.querySelector('iframe.giscus-frame');
|
||
if (!iframe) return;
|
||
iframe.contentWindow.postMessage({ giscus: message }, 'https://giscus.app');
|
||
}
|
||
sendMessage({
|
||
setConfig: {
|
||
theme: newTheme
|
||
}
|
||
});
|
||
}
|
||
const isGiscussLoaded = window.document.querySelector('iframe.giscus-frame') !== null;
|
||
if (isGiscussLoaded) {
|
||
changeGiscusTheme();
|
||
}
|
||
};
|
||
const queryPrefersDark = window.matchMedia('(prefers-color-scheme: dark)');
|
||
const darkModeDefault = queryPrefersDark.matches;
|
||
document.querySelector('link.quarto-color-scheme-extra').rel = 'disabled-stylesheet';
|
||
let localAlternateSentinel = darkModeDefault ? 'alternate' : 'default';
|
||
// Dark / light mode switch
|
||
window.quartoToggleColorScheme = () => {
|
||
// Read the current dark / light value
|
||
let toAlternate = !window.hasAlternateSentinel();
|
||
toggleColorMode(toAlternate);
|
||
setStyleSentinel(toAlternate);
|
||
toggleGiscusIfUsed(toAlternate, darkModeDefault);
|
||
};
|
||
queryPrefersDark.addEventListener("change", e => {
|
||
if(window.localStorage.getItem("quarto-color-scheme") !== null)
|
||
return;
|
||
const alternate = e.matches
|
||
toggleColorMode(alternate);
|
||
localAlternateSentinel = e.matches ? 'alternate' : 'default'; // this is used alongside local storage!
|
||
toggleGiscusIfUsed(alternate, darkModeDefault);
|
||
});
|
||
// Switch to dark mode if need be
|
||
if (window.hasAlternateSentinel()) {
|
||
toggleColorMode(true);
|
||
} else {
|
||
toggleColorMode(false);
|
||
}
|
||
</script>
|
||
|
||
<div id="quarto-search-results"></div>
|
||
<header id="quarto-header" class="headroom fixed-top">
|
||
<nav class="navbar navbar-expand-lg " data-bs-theme="dark">
|
||
<div class="navbar-container container-fluid">
|
||
<div class="navbar-brand-container mx-auto">
|
||
<a class="navbar-brand" href="../index.html">
|
||
<span class="navbar-title">Nicole Dresselhaus</span>
|
||
</a>
|
||
</div>
|
||
<div id="quarto-search" class="" title="Suchen"></div>
|
||
<button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarCollapse" aria-controls="navbarCollapse" role="menu" aria-expanded="false" aria-label="Navigation umschalten" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
|
||
<span class="navbar-toggler-icon"></span>
|
||
</button>
|
||
<div class="collapse navbar-collapse" id="navbarCollapse">
|
||
<ul class="navbar-nav navbar-nav-scroll me-auto">
|
||
<li class="nav-item">
|
||
<a class="nav-link" href="../index.html"> <i class="bi bi-house" role="img">
|
||
</i>
|
||
<span class="menu-text">Home</span></a>
|
||
</li>
|
||
<li class="nav-item">
|
||
<a class="nav-link active" href="../About/index.html" aria-current="page"> <i class="bi bi-file-person" role="img">
|
||
</i>
|
||
<span class="menu-text">About</span></a>
|
||
</li>
|
||
</ul>
|
||
<ul class="navbar-nav navbar-nav-scroll ms-auto">
|
||
<li class="nav-item compact">
|
||
<a class="nav-link" href="../index.xml"> <i class="bi bi-rss" role="img">
|
||
</i>
|
||
<span class="menu-text"></span></a>
|
||
</li>
|
||
</ul>
|
||
</div> <!-- /navcollapse -->
|
||
<div class="quarto-navbar-tools">
|
||
<a href="" class="quarto-color-scheme-toggle quarto-navigation-tool px-1" onclick="window.quartoToggleColorScheme(); return false;" title="Dunkelmodus umschalten"><i class="bi"></i></a>
|
||
<a href="" class="quarto-reader-toggle quarto-navigation-tool px-1" onclick="window.quartoToggleReader(); return false;" title="Lesemodus umschalten">
|
||
<div class="quarto-reader-toggle-btn">
|
||
<i class="bi"></i>
|
||
</div>
|
||
</a>
|
||
</div>
|
||
</div> <!-- /container-fluid -->
|
||
</nav>
|
||
<nav class="quarto-secondary-nav">
|
||
<div class="container-fluid d-flex">
|
||
<button type="button" class="quarto-btn-toggle btn" data-bs-toggle="collapse" role="button" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Seitenleiste umschalten" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
|
||
<i class="bi bi-layout-text-sidebar-reverse"></i>
|
||
</button>
|
||
<nav class="quarto-page-breadcrumbs" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item">Serious</li><li class="breadcrumb-item"><a href="../Writing/coding-age-ai.html">Writing</a></li><li class="breadcrumb-item"><a href="../Writing/coding-age-ai.html">Field Report: Coding in the Age of AI with Cursor</a></li></ol></nav>
|
||
<a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" aria-controls="quarto-sidebar" aria-expanded="false" aria-label="Seitenleiste umschalten" onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">
|
||
</a>
|
||
</div>
|
||
</nav>
|
||
</header>
|
||
<!-- content -->
|
||
<div id="quarto-content" class="quarto-container page-columns page-rows-contents page-layout-article page-navbar">
|
||
<!-- sidebar -->
|
||
<nav id="quarto-sidebar" class="sidebar collapse collapse-horizontal quarto-sidebar-collapse-item sidebar-navigation docked overflow-auto">
|
||
<div class="sidebar-menu-container">
|
||
<ul class="list-unstyled mt-1">
|
||
<li class="sidebar-item sidebar-item-section">
|
||
<div class="sidebar-item-container">
|
||
<a class="sidebar-item-text sidebar-link text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-1" role="navigation" aria-expanded="true">
|
||
<span class="menu-text">Serious</span></a>
|
||
<a class="sidebar-item-toggle text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-1" role="navigation" aria-expanded="true" aria-label="Abschnitt umschalten">
|
||
<i class="bi bi-chevron-right ms-2"></i>
|
||
</a>
|
||
</div>
|
||
<ul id="quarto-sidebar-section-1" class="collapse list-unstyled sidebar-section depth1 show">
|
||
<li class="sidebar-item sidebar-item-section">
|
||
<div class="sidebar-item-container">
|
||
<a class="sidebar-item-text sidebar-link text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-2" role="navigation" aria-expanded="true">
|
||
<span class="menu-text">Writing</span></a>
|
||
<a class="sidebar-item-toggle text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-2" role="navigation" aria-expanded="true" aria-label="Abschnitt umschalten">
|
||
<i class="bi bi-chevron-right ms-2"></i>
|
||
</a>
|
||
</div>
|
||
<ul id="quarto-sidebar-section-2" class="collapse list-unstyled sidebar-section depth2 show">
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Writing/coding-age-ai.html" class="sidebar-item-text sidebar-link active">
|
||
<span class="menu-text">Field Report: Coding in the Age of AI with Cursor</span></a>
|
||
</div>
|
||
</li>
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Writing/documentation.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Anforderungskatalog für die Dokumentation von Forschungssoftware (Digital Humanities)</span></a>
|
||
</div>
|
||
</li>
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Writing/ner4all-case-study.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Case Study: Local LLM-Based NER with n8n and Ollama</span></a>
|
||
</div>
|
||
</li>
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Writing/Obsidian-RAG.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">RAG für eine Obsidian-Wissensdatenbank: Technische Ansätze</span></a>
|
||
</div>
|
||
</li>
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Obsidian-Articles/Artikelbewertung durch LLM.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Artikelbewertung durch ein Large Language Model (LLM) - Ein Beispiel aus der Praxis</span></a>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="sidebar-item sidebar-item-section">
|
||
<div class="sidebar-item-container">
|
||
<a class="sidebar-item-text sidebar-link text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-3" role="navigation" aria-expanded="false">
|
||
<span class="menu-text">Coding</span></a>
|
||
<a class="sidebar-item-toggle text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-3" role="navigation" aria-expanded="false" aria-label="Abschnitt umschalten">
|
||
<i class="bi bi-chevron-right ms-2"></i>
|
||
</a>
|
||
</div>
|
||
<ul id="quarto-sidebar-section-3" class="collapse list-unstyled sidebar-section depth2 ">
|
||
<li class="sidebar-item sidebar-item-section">
|
||
<div class="sidebar-item-container">
|
||
<a class="sidebar-item-text sidebar-link text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-4" role="navigation" aria-expanded="false">
|
||
<span class="menu-text">Haskell</span></a>
|
||
<a class="sidebar-item-toggle text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-4" role="navigation" aria-expanded="false" aria-label="Abschnitt umschalten">
|
||
<i class="bi bi-chevron-right ms-2"></i>
|
||
</a>
|
||
</div>
|
||
<ul id="quarto-sidebar-section-4" class="collapse list-unstyled sidebar-section depth3 ">
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Coding/Haskell/Advantages.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Talks und Posts zu Haskell</span></a>
|
||
</div>
|
||
</li>
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Coding/Haskell/FFPiH.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Fortgeschrittene funktionale Programmierung in Haskell</span></a>
|
||
</div>
|
||
</li>
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Coding/Haskell/Lenses.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Lenses</span></a>
|
||
</div>
|
||
</li>
|
||
<li class="sidebar-item sidebar-item-section">
|
||
<div class="sidebar-item-container">
|
||
<a class="sidebar-item-text sidebar-link text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-5" role="navigation" aria-expanded="false">
|
||
<span class="menu-text">Code Snippets</span></a>
|
||
<a class="sidebar-item-toggle text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-5" role="navigation" aria-expanded="false" aria-label="Abschnitt umschalten">
|
||
<i class="bi bi-chevron-right ms-2"></i>
|
||
</a>
|
||
</div>
|
||
<ul id="quarto-sidebar-section-5" class="collapse list-unstyled sidebar-section depth4 ">
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Coding/Haskell/Code Snippets/Monoid.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Monoid? Da war doch was…</span></a>
|
||
</div>
|
||
</li>
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Coding/Haskell/Code Snippets/Morphisms.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">*-Morpisms</span></a>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="sidebar-item sidebar-item-section">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Coding/Haskell/Webapp-Example/index.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Webapp-Development in Haskell</span></a>
|
||
<a class="sidebar-item-toggle text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-6" role="navigation" aria-expanded="false" aria-label="Abschnitt umschalten">
|
||
<i class="bi bi-chevron-right ms-2"></i>
|
||
</a>
|
||
</div>
|
||
<ul id="quarto-sidebar-section-6" class="collapse list-unstyled sidebar-section depth4 ">
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Coding/Haskell/Webapp-Example/Main.hs.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Webapp-Example: Main.hs</span></a>
|
||
</div>
|
||
</li>
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Coding/Haskell/Webapp-Example/MyService_Types.hs.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Webapp-Example: MyService/Types.hs</span></a>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="sidebar-item sidebar-item-section">
|
||
<div class="sidebar-item-container">
|
||
<a class="sidebar-item-text sidebar-link text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-7" role="navigation" aria-expanded="false">
|
||
<span class="menu-text">Health</span></a>
|
||
<a class="sidebar-item-toggle text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-7" role="navigation" aria-expanded="false" aria-label="Abschnitt umschalten">
|
||
<i class="bi bi-chevron-right ms-2"></i>
|
||
</a>
|
||
</div>
|
||
<ul id="quarto-sidebar-section-7" class="collapse list-unstyled sidebar-section depth2 ">
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Health/Issues.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Mental Health</span></a>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="sidebar-item sidebar-item-section">
|
||
<div class="sidebar-item-container">
|
||
<a class="sidebar-item-text sidebar-link text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-8" role="navigation" aria-expanded="false">
|
||
<span class="menu-text">Uni</span></a>
|
||
<a class="sidebar-item-toggle text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-8" role="navigation" aria-expanded="false" aria-label="Abschnitt umschalten">
|
||
<i class="bi bi-chevron-right ms-2"></i>
|
||
</a>
|
||
</div>
|
||
<ul id="quarto-sidebar-section-8" class="collapse list-unstyled sidebar-section depth2 ">
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Uni/Lernerfolg_an_der_Uni.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Wie lerne ich richtig an der Uni?</span></a>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="px-0"><hr class="sidebar-divider hi "></li>
|
||
<li class="sidebar-item sidebar-item-section">
|
||
<div class="sidebar-item-container">
|
||
<a class="sidebar-item-text sidebar-link text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-9" role="navigation" aria-expanded="true">
|
||
<span class="menu-text">Fun</span></a>
|
||
<a class="sidebar-item-toggle text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-9" role="navigation" aria-expanded="true" aria-label="Abschnitt umschalten">
|
||
<i class="bi bi-chevron-right ms-2"></i>
|
||
</a>
|
||
</div>
|
||
<ul id="quarto-sidebar-section-9" class="collapse list-unstyled sidebar-section depth1 show">
|
||
<li class="sidebar-item sidebar-item-section">
|
||
<div class="sidebar-item-container">
|
||
<a class="sidebar-item-text sidebar-link text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-10" role="navigation" aria-expanded="false">
|
||
<span class="menu-text">Opinions</span></a>
|
||
<a class="sidebar-item-toggle text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-10" role="navigation" aria-expanded="false" aria-label="Abschnitt umschalten">
|
||
<i class="bi bi-chevron-right ms-2"></i>
|
||
</a>
|
||
</div>
|
||
<ul id="quarto-sidebar-section-10" class="collapse list-unstyled sidebar-section depth2 ">
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Opinions/Editors.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Editors</span></a>
|
||
</div>
|
||
</li>
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Opinions/Keyboard-Layout.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Keyboard-Layout</span></a>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="sidebar-item sidebar-item-section">
|
||
<div class="sidebar-item-container">
|
||
<a class="sidebar-item-text sidebar-link text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-11" role="navigation" aria-expanded="false">
|
||
<span class="menu-text">Stuff</span></a>
|
||
<a class="sidebar-item-toggle text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-11" role="navigation" aria-expanded="false" aria-label="Abschnitt umschalten">
|
||
<i class="bi bi-chevron-right ms-2"></i>
|
||
</a>
|
||
</div>
|
||
<ul id="quarto-sidebar-section-11" class="collapse list-unstyled sidebar-section depth2 ">
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../Stuff/Bielefeldverschwoerung.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Die Bielefeld-Verschwörung</span></a>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="px-0"><hr class="sidebar-divider hi "></li>
|
||
<li class="sidebar-item sidebar-item-section">
|
||
<div class="sidebar-item-container">
|
||
<a class="sidebar-item-text sidebar-link text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-12" role="navigation" aria-expanded="true">
|
||
<span class="menu-text">Info</span></a>
|
||
<a class="sidebar-item-toggle text-start" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-12" role="navigation" aria-expanded="true" aria-label="Abschnitt umschalten">
|
||
<i class="bi bi-chevron-right ms-2"></i>
|
||
</a>
|
||
</div>
|
||
<ul id="quarto-sidebar-section-12" class="collapse list-unstyled sidebar-section depth1 show">
|
||
<li class="sidebar-item sidebar-item-section">
|
||
<div class="sidebar-item-container">
|
||
<a href="../About/index.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">About me</span></a>
|
||
<a class="sidebar-item-toggle text-start collapsed" data-bs-toggle="collapse" data-bs-target="#quarto-sidebar-section-13" role="navigation" aria-expanded="false" aria-label="Abschnitt umschalten">
|
||
<i class="bi bi-chevron-right ms-2"></i>
|
||
</a>
|
||
</div>
|
||
<ul id="quarto-sidebar-section-13" class="collapse list-unstyled sidebar-section depth2 ">
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../About/Experience.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Highlights of my experiences in the programming world</span></a>
|
||
</div>
|
||
</li>
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../About/Extracurricular.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Studium generale / University-Life</span></a>
|
||
</div>
|
||
</li>
|
||
<li class="sidebar-item">
|
||
<div class="sidebar-item-container">
|
||
<a href="../About/Work.html" class="sidebar-item-text sidebar-link">
|
||
<span class="menu-text">Work-Experience</span></a>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
<div id="quarto-sidebar-glass" class="quarto-sidebar-collapse-item" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item"></div>
|
||
<!-- margin-sidebar -->
|
||
<div id="quarto-margin-sidebar" class="sidebar margin-sidebar">
|
||
<nav id="TOC" role="doc-toc" class="toc-active">
|
||
<h2 id="toc-title">Auf dieser Seite</h2>
|
||
|
||
<ul>
|
||
<li><a href="#introduction" id="toc-introduction" class="nav-link active" data-scroll-target="#introduction">Introduction</a></li>
|
||
<li><a href="#how-to-program-with-cursor" id="toc-how-to-program-with-cursor" class="nav-link" data-scroll-target="#how-to-program-with-cursor">How to program with Cursor</a>
|
||
<ul class="collapse">
|
||
<li><a href="#capabilities-general-procedure" id="toc-capabilities-general-procedure" class="nav-link" data-scroll-target="#capabilities-general-procedure">Capabilities / General procedure</a></li>
|
||
<li><a href="#lessons-from-project-management" id="toc-lessons-from-project-management" class="nav-link" data-scroll-target="#lessons-from-project-management">Lessons from Project Management</a></li>
|
||
</ul></li>
|
||
<li><a href="#implementation" id="toc-implementation" class="nav-link" data-scroll-target="#implementation">Implementation</a>
|
||
<ul class="collapse">
|
||
<li><a href="#the-rules" id="toc-the-rules" class="nav-link" data-scroll-target="#the-rules">The Rules</a></li>
|
||
</ul></li>
|
||
<li><a href="#example-rules-in-action" id="toc-example-rules-in-action" class="nav-link" data-scroll-target="#example-rules-in-action">Example: Rules in Action</a>
|
||
<ul class="collapse">
|
||
<li><a href="#analyzing-the-situation" id="toc-analyzing-the-situation" class="nav-link" data-scroll-target="#analyzing-the-situation">Analyzing the situation</a></li>
|
||
<li><a href="#correcting-the-analysis" id="toc-correcting-the-analysis" class="nav-link" data-scroll-target="#correcting-the-analysis">Correcting the analysis</a></li>
|
||
<li><a href="#creating-tasks" id="toc-creating-tasks" class="nav-link" data-scroll-target="#creating-tasks">Creating Tasks</a></li>
|
||
<li><a href="#executing" id="toc-executing" class="nav-link" data-scroll-target="#executing">Executing</a></li>
|
||
</ul></li>
|
||
<li><a href="#result" id="toc-result" class="nav-link" data-scroll-target="#result">Result</a></li>
|
||
</ul>
|
||
<div class="quarto-other-links"><h2>Weitere Links</h2><ul><li><a href="https://gitea.dresselhaus.cloud/Drezil/quarto/src/branch/main/Writing/coding-age-ai.md"><i class="bi bi-filetype-md"></i>Source of this article</a></li><li><a href="https://pages.cms.hu-berlin.de/methodenlabor/p_gitlab-overviewer/"><i class="bi bi-filetype-doc"></i>Documentation for gitlab_overviewer</a></li></ul></div></nav>
|
||
</div>
|
||
<!-- main -->
|
||
<main class="content page-columns page-full" id="quarto-document-content">
|
||
|
||
|
||
<header id="title-block-header" class="quarto-title-block default"><nav class="quarto-page-breadcrumbs quarto-title-breadcrumbs d-none d-lg-block" aria-label="breadcrumb"><ol class="breadcrumb"><li class="breadcrumb-item">Serious</li><li class="breadcrumb-item"><a href="../Writing/coding-age-ai.html">Writing</a></li><li class="breadcrumb-item"><a href="../Writing/coding-age-ai.html">Field Report: Coding in the Age of AI with Cursor</a></li></ol></nav>
|
||
<div class="quarto-title">
|
||
<h1 class="title">Field Report: Coding in the Age of AI with Cursor</h1>
|
||
</div>
|
||
|
||
<div>
|
||
<div class="description">
|
||
<p>A real Field Report out of the trences of AI-assisted coding with its ups and downs.</p>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="quarto-title-meta-author">
|
||
<div class="quarto-title-meta-heading">Autor:in</div>
|
||
<div class="quarto-title-meta-heading">Zugehörigkeit</div>
|
||
|
||
<div class="quarto-title-meta-contents">
|
||
<p class="author">Nicole Dresselhaus <a href="mailto:nicole.dresselhaus@hu-berlin.de" class="quarto-title-author-email"><i class="bi bi-envelope"></i></a> <a href="https://orcid.org/0009-0008-8850-3679" class="quarto-title-author-orcid"> <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAYAAAAf8/9hAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAA2ZpVFh0WE1MOmNvbS5hZG9iZS54bXAAAAAAADw/eHBhY2tldCBiZWdpbj0i77u/IiBpZD0iVzVNME1wQ2VoaUh6cmVTek5UY3prYzlkIj8+IDx4OnhtcG1ldGEgeG1sbnM6eD0iYWRvYmU6bnM6bWV0YS8iIHg6eG1wdGs9IkFkb2JlIFhNUCBDb3JlIDUuMC1jMDYwIDYxLjEzNDc3NywgMjAxMC8wMi8xMi0xNzozMjowMCAgICAgICAgIj4gPHJkZjpSREYgeG1sbnM6cmRmPSJodHRwOi8vd3d3LnczLm9yZy8xOTk5LzAyLzIyLXJkZi1zeW50YXgtbnMjIj4gPHJkZjpEZXNjcmlwdGlvbiByZGY6YWJvdXQ9IiIgeG1sbnM6eG1wTU09Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC9tbS8iIHhtbG5zOnN0UmVmPSJodHRwOi8vbnMuYWRvYmUuY29tL3hhcC8xLjAvc1R5cGUvUmVzb3VyY2VSZWYjIiB4bWxuczp4bXA9Imh0dHA6Ly9ucy5hZG9iZS5jb20veGFwLzEuMC8iIHhtcE1NOk9yaWdpbmFsRG9jdW1lbnRJRD0ieG1wLmRpZDo1N0NEMjA4MDI1MjA2ODExOTk0QzkzNTEzRjZEQTg1NyIgeG1wTU06RG9jdW1lbnRJRD0ieG1wLmRpZDozM0NDOEJGNEZGNTcxMUUxODdBOEVCODg2RjdCQ0QwOSIgeG1wTU06SW5zdGFuY2VJRD0ieG1wLmlpZDozM0NDOEJGM0ZGNTcxMUUxODdBOEVCODg2RjdCQ0QwOSIgeG1wOkNyZWF0b3JUb29sPSJBZG9iZSBQaG90b3Nob3AgQ1M1IE1hY2ludG9zaCI+IDx4bXBNTTpEZXJpdmVkRnJvbSBzdFJlZjppbnN0YW5jZUlEPSJ4bXAuaWlkOkZDN0YxMTc0MDcyMDY4MTE5NUZFRDc5MUM2MUUwNEREIiBzdFJlZjpkb2N1bWVudElEPSJ4bXAuZGlkOjU3Q0QyMDgwMjUyMDY4MTE5OTRDOTM1MTNGNkRBODU3Ii8+IDwvcmRmOkRlc2NyaXB0aW9uPiA8L3JkZjpSREY+IDwveDp4bXBtZXRhPiA8P3hwYWNrZXQgZW5kPSJyIj8+84NovQAAAR1JREFUeNpiZEADy85ZJgCpeCB2QJM6AMQLo4yOL0AWZETSqACk1gOxAQN+cAGIA4EGPQBxmJA0nwdpjjQ8xqArmczw5tMHXAaALDgP1QMxAGqzAAPxQACqh4ER6uf5MBlkm0X4EGayMfMw/Pr7Bd2gRBZogMFBrv01hisv5jLsv9nLAPIOMnjy8RDDyYctyAbFM2EJbRQw+aAWw/LzVgx7b+cwCHKqMhjJFCBLOzAR6+lXX84xnHjYyqAo5IUizkRCwIENQQckGSDGY4TVgAPEaraQr2a4/24bSuoExcJCfAEJihXkWDj3ZAKy9EJGaEo8T0QSxkjSwORsCAuDQCD+QILmD1A9kECEZgxDaEZhICIzGcIyEyOl2RkgwAAhkmC+eAm0TAAAAABJRU5ErkJggg=="></a></p>
|
||
</div>
|
||
<div class="quarto-title-meta-contents">
|
||
<p class="affiliation">
|
||
<a href="https://hu-berlin.de">
|
||
Humboldt-Universität zu Berlin
|
||
</a>
|
||
</p>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="quarto-title-meta">
|
||
|
||
|
||
<div>
|
||
<div class="quarto-title-meta-heading">Veröffentlichungsdatum</div>
|
||
<div class="quarto-title-meta-contents">
|
||
<p class="date">26. Juni 2025</p>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
|
||
<div>
|
||
<div class="abstract">
|
||
<div class="block-title">Zusammenfassung</div>
|
||
<p>This report presents practical methodologies and best practices for developing software using Cursor, an AI-assisted IDE. The paper details a structured workflow that emphasizes specification-driven development, comprehensive documentation practices, and systematic task management to maintain quality control when working with language models. Through detailed examples and rule configurations, it demonstrates how to leverage AI capabilities while mitigating common pitfalls such as redundant code generation and context limitations. The methodology presented includes comprehensive PRD (Product Requirement Document) creation, specification adherence checks, and task breakdown systems that ensure alignment between human intent and AI execution. This guide serves as a practical reference for developers seeking to effectively integrate AI tools into their software development workflow while maintaining project integrity and scalability.</p>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</header>
|
||
|
||
|
||
<section id="introduction" class="level2 page-columns page-full">
|
||
<h2 class="anchored" data-anchor-id="introduction">Introduction</h2>
|
||
<p>In the fast eveolving field of AI there is a clear lack of reports on “what really works”. Some techniques hailed as revolution (like the DeepSeek Aha-Moment<span class="citation" data-cites="DeepSeek-AI2025DeepSeekR1IncentivizingReasoning">[<a href="#ref-DeepSeek-AI2025DeepSeekR1IncentivizingReasoning" role="doc-biblioref">1</a>]</span>) for unlimited potential were soon realized to “just” optimize nieche problems that can benchmarked<span class="citation" data-cites="Shao2025SpuriousRewardsRethinking">[<a href="#ref-Shao2025SpuriousRewardsRethinking" role="doc-biblioref">2</a>]</span><a href="#fn1" class="footnote-ref" id="fnref1" role="doc-noteref"><sup>1</sup></a>.</p>
|
||
<div class="no-row-height column-margin column-container"><div id="fn1"><p><sup>1</sup> Like all decent humans i ain’t got time to read up on everything - so a big shoutout to <span class="citation" data-cites="bycloud2025LLMsRLRevelation">[<a href="#ref-bycloud2025LLMsRLRevelation" role="doc-biblioref">3</a>]</span> for doing thorough reviews on ML-topics and linking the respective papers!</p></div><div id="fn2"><p><sup>2</sup> i.e. the “base model” nearly all papers tested their finding on (qwen-series) also gets better with RLVR-optimization if rewards are random instead of verified</p></div></div><p>I personally think it is an exercise in futility to get a <em>current</em> theoretical overview for forming a decent grounded opinion on the state of things. Even before one is done analyzing the literature, crossrefercencing and collecting evidence and then finally formulating methods and implementing them, the next revolution comes around that could put everything on its head again. In the afromentioned example the community went from “Reasoning is the solution” in January<span class="citation" data-cites="DeepSeek-AI2025DeepSeekR1IncentivizingReasoning">[<a href="#ref-DeepSeek-AI2025DeepSeekR1IncentivizingReasoning" role="doc-biblioref">1</a>]</span> over first critical views in March<span class="citation" data-cites="Liu2025UnderstandingR1ZeroLikeTraining">[<a href="#ref-Liu2025UnderstandingR1ZeroLikeTraining" role="doc-biblioref">4</a>]</span> to doubts on that claims validity of generating concepts previously not present in the base model in May<span class="citation" data-cites="Mukherjee2025ReinforcementLearningFinetunes">[<a href="#ref-Mukherjee2025ReinforcementLearningFinetunes" role="doc-biblioref">5</a>]</span> to complete ad-absurdum in June<span class="citation" data-cites="Shao2025SpuriousRewardsRethinking">[<a href="#ref-Shao2025SpuriousRewardsRethinking" role="doc-biblioref">2</a>]</span><a href="#fn2" class="footnote-ref" id="fnref2" role="doc-noteref"><sup>2</sup></a>.</p>
|
||
<p>Therefore see this “Field Guide” for what it is: A current state of things that work for at least 1 individuum in exactly this ecosystem at this point in time.</p>
|
||
</section>
|
||
<section id="how-to-program-with-cursor" class="level2">
|
||
<h2 class="anchored" data-anchor-id="how-to-program-with-cursor">How to program with Cursor</h2>
|
||
<p>In essence <a href="https://cursor.com">Cursor</a> is “just” a fork of <a href="https://code.visualstudio.com/">Microsofts VSCode</a> with some added functionality: Automatically injecting files into LLM-Prompts, offering tool-aware LLMs to use <a href="https://modelcontextprotocol.io/introduction">MCP</a>s, read the filesystem, execute arbitrary commands in the shell (either automomatically or after permission), getting feedback from the editor (i.e. installed linters, language-servers etc.) and thus have the same (or even better) information/tools available as the programmer in front of the screen.</p>
|
||
<section id="capabilities-general-procedure" class="level3">
|
||
<h3 class="anchored" data-anchor-id="capabilities-general-procedure">Capabilities / General procedure</h3>
|
||
<p>The main issue is now: theoretically agentic IDEs can get all information - practically it is limited directly by token-window sizes, costs of these queries; and indirectly by outsourced costs like environmental impacts, data-security, etc. The suppliers of such services can claim privacy as much as they want - it can’t be proven and (especially under US-Law) is not even possible to resist lawful orders (including the gag-order to not talk about these).</p>
|
||
<p>In practise one feels the direct pain points more severly. Some regular examples include generating redundant code, because the current context was not aware of utility-modules and functions it could use - leading to huge technical debt in no time.</p>
|
||
<p>Therefore my preferred workflow is to “think bigger”. Imagine being a product owner of a huge, sluggish company. The left hand never knows what the right hand does or has done (i.e. the LLM forgetting things already exist in the codebase), everything has to be rigorous defined, specified and enforced. Some people reported good results with Test-Driven-Development (TDD) - but in my experience these things only prevent regressions and not proactively enforce the desired agent behaviour.</p>
|
||
</section>
|
||
<section id="lessons-from-project-management" class="level3">
|
||
<h3 class="anchored" data-anchor-id="lessons-from-project-management">Lessons from Project Management</h3>
|
||
<p>This may be a <em>duh!</em>-Moment for people longer in Software-Engineering, but most of the time is getting the specifications of what you want to build right. Asking questions. Interviewing stakeholders. Gathering user experience reports. Most of it is not actually writing code - but deciding on what to write and how.</p>
|
||
<p>For this i created some rules in my workflow that interleave with their responsibilities and outcomes. Especially in the planning phase the LLM is encouraged to ask questions, find edge-cases or even look at other implementations. One could also think of letting the agent do a websearch, read reports and forums on how good which framework works and then arguments on why this framework is good - and also why it is not good. The last decision of all pro/contra is by the actual human.</p>
|
||
<p>The main theme always follows a similar pattern:</p>
|
||
<ul>
|
||
<li>A <strong>need</strong> is found.<br>
|
||
This could be a bug, a feature, some changes to existing behaviour etc.</li>
|
||
<li>An investigation is launched, yielding a <strong>Product Requirement Document (PRD)</strong>.<br>
|
||
This dives into the codebase to asses the current state of things. Maybe some bugs are obvious and easily fixed.<br>
|
||
This formalizes that the LLM understood what <em>should</em> be done and especially what is <em>out of scope</em>.</li>
|
||
<li>Pin the desired behaviour in a <strong>Specification</strong>.<br>
|
||
Either this means changing currently established specifications (i.e. bug/chang) or writing complete new ones (i.e. feature).</li>
|
||
<li>Investigate <strong>Spec-Compliance</strong>.<br>
|
||
Again the agentlooks at the codebase to identify <em>where</em> things should change and <em>how</em>. Also recommendation are made on how it could achieve the goal.</li>
|
||
<li>Generate <strong>Tasks</strong>.<br>
|
||
From the compliance-report of spec-deviations (either from a bug or from a new/changed spec) finally a Plan to fix everything can be derived (think: Sprint-Planning).</li>
|
||
<li><strong>NOTE: Up to here the agent never touched the code.</strong></li>
|
||
<li>Finally <strong>Implement the change</strong>.<br>
|
||
This is most often the most trivial step. Everything is known and formulated for “simple” Agents to just follow. It names files needed, specs to follow, guidelines on how to do things in the repository etc.</li>
|
||
</ul>
|
||
</section>
|
||
</section>
|
||
<section id="implementation" class="level2 page-columns page-full">
|
||
<h2 class="anchored" data-anchor-id="implementation">Implementation</h2>
|
||
<p>I only go briefly over the most important aspects of the implementation in Rules and their results. As this is also evolving with experience, there will be updates to those on the published place.</p>
|
||
<section id="the-rules" class="level3 page-columns page-full">
|
||
<h3 class="anchored" data-anchor-id="the-rules">The Rules</h3>
|
||
<p>Cursor rules are written in markdown with a small yaml-frontmatter. <code>description</code> is a string providing the agent with a description of the rule so it can be called like a tool (and basically injects the rule-content into the context). <code>globs</code> automatically inject the rule when the glob matches one attached filename. <code>alwaysApply</code> injects the rule into all contexts-windows.</p>
|
||
<section id="always-apply-rule-basic-info-and-behaviour" class="level4 page-columns page-full">
|
||
<h4 class="anchored" data-anchor-id="always-apply-rule-basic-info-and-behaviour">Always apply rule: Basic info and behaviour</h4>
|
||
<p>This tells the agent the project-structure and fixes some common pitfalls (i.e. the agent assuming <code>bash</code>, getting sidetracked, etc.).</p>
|
||
<div class="column-page-right">
|
||
<div class="sourceCode" id="cb1"><pre class="sourceCode markdown code-with-copy"><code class="sourceCode markdown"><span id="cb1-1"><a href="#cb1-1" aria-hidden="true" tabindex="-1"></a><span class="co">---</span></span>
|
||
<span id="cb1-2"><a href="#cb1-2" aria-hidden="true" tabindex="-1"></a><span class="an">description:</span></span>
|
||
<span id="cb1-3"><a href="#cb1-3" aria-hidden="true" tabindex="-1"></a><span class="an">globs:</span></span>
|
||
<span id="cb1-4"><a href="#cb1-4" aria-hidden="true" tabindex="-1"></a><span class="an">alwaysApply:</span><span class="co"> true</span></span>
|
||
<span id="cb1-5"><a href="#cb1-5" aria-hidden="true" tabindex="-1"></a><span class="co">---</span></span>
|
||
<span id="cb1-6"><a href="#cb1-6" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb1-7"><a href="#cb1-7" aria-hidden="true" tabindex="-1"></a><span class="fu"># IMPORTANT INFORMATION! DO NOT FORGET!</span></span>
|
||
<span id="cb1-8"><a href="#cb1-8" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb1-9"><a href="#cb1-9" aria-hidden="true" tabindex="-1"></a><span class="fu">## Conventions</span></span>
|
||
<span id="cb1-10"><a href="#cb1-10" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb1-11"><a href="#cb1-11" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Run tests with <span class="in">`poetry run pytest`</span>.</span>
|
||
<span id="cb1-12"><a href="#cb1-12" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**NO BASH IDIOMS IN COMMANDS**. Do not assume bash-usage. Use temporary</span>
|
||
<span id="cb1-13"><a href="#cb1-13" aria-hidden="true" tabindex="-1"></a> scripts instead of bash-idoms like <span class="in">`<<`</span> for text-input to a process.</span>
|
||
<span id="cb1-14"><a href="#cb1-14" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Ask to update corresponding spec when you detect or implement a behaviour</span>
|
||
<span id="cb1-15"><a href="#cb1-15" aria-hidden="true" tabindex="-1"></a> change.</span>
|
||
<span id="cb1-16"><a href="#cb1-16" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Mention every time things are not implemented according to spec and offer to</span>
|
||
<span id="cb1-17"><a href="#cb1-17" aria-hidden="true" tabindex="-1"></a> make them compliant.</span>
|
||
<span id="cb1-18"><a href="#cb1-18" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb1-19"><a href="#cb1-19" aria-hidden="true" tabindex="-1"></a><span class="fu">## Behavior of the Agent</span></span>
|
||
<span id="cb1-20"><a href="#cb1-20" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb1-21"><a href="#cb1-21" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>If you have a task, ONLY do the task. Do not get distracted by failing tests,</span>
|
||
<span id="cb1-22"><a href="#cb1-22" aria-hidden="true" tabindex="-1"></a> missing data etc. not related to your task.</span>
|
||
<span id="cb1-23"><a href="#cb1-23" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Spec compliance is key. Check corresponding specs before you fix behaviour or</span>
|
||
<span id="cb1-24"><a href="#cb1-24" aria-hidden="true" tabindex="-1"></a> ask the user if you should proceed.</span>
|
||
<span id="cb1-25"><a href="#cb1-25" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb1-26"><a href="#cb1-26" aria-hidden="true" tabindex="-1"></a><span class="fu">## Where to look for information?</span></span>
|
||
<span id="cb1-27"><a href="#cb1-27" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb1-28"><a href="#cb1-28" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Status & changes: <span class="in">`git status`</span>, test failures in <span class="in">`tests/`</span></span>
|
||
<span id="cb1-29"><a href="#cb1-29" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Active feature work: <span class="in">`/tasks/<feature>/TASKS.md`</span></span>
|
||
<span id="cb1-30"><a href="#cb1-30" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Feature requirements: <span class="in">`/tasks/<feature>/PRD.md`</span></span>
|
||
<span id="cb1-31"><a href="#cb1-31" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Feature specifications: <span class="in">`/specs/`</span></span>
|
||
<span id="cb1-32"><a href="#cb1-32" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Source code: <span class="in">`/src/`</span></span>
|
||
<span id="cb1-33"><a href="#cb1-33" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Tests & fixtures: <span class="in">`/tests/`</span></span>
|
||
<span id="cb1-34"><a href="#cb1-34" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>CLI entry point: <span class="in">`/src/<project>/cli/__main__.py`</span></span></code><button title="In die Zwischenablage kopieren" class="code-copy-button"><i class="bi"></i></button></pre></div>
|
||
</div>
|
||
</section>
|
||
<section id="get-the-prd" class="level4 page-columns page-full">
|
||
<h4 class="anchored" data-anchor-id="get-the-prd">Get the PRD</h4>
|
||
<div class="column-page-right">
|
||
<div class="sourceCode" id="cb2"><pre class="sourceCode markdown code-with-copy"><code class="sourceCode markdown"><span id="cb2-1"><a href="#cb2-1" aria-hidden="true" tabindex="-1"></a><span class="co">---</span></span>
|
||
<span id="cb2-2"><a href="#cb2-2" aria-hidden="true" tabindex="-1"></a><span class="an">description:</span></span>
|
||
<span id="cb2-3"><a href="#cb2-3" aria-hidden="true" tabindex="-1"></a><span class="an">globs:</span></span>
|
||
<span id="cb2-4"><a href="#cb2-4" aria-hidden="true" tabindex="-1"></a><span class="an">alwaysApply:</span><span class="co"> false</span></span>
|
||
<span id="cb2-5"><a href="#cb2-5" aria-hidden="true" tabindex="-1"></a><span class="co">---</span></span>
|
||
<span id="cb2-6"><a href="#cb2-6" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb2-7"><a href="#cb2-7" aria-hidden="true" tabindex="-1"></a><span class="fu">## Product Requirements Document (PRD)</span></span>
|
||
<span id="cb2-8"><a href="#cb2-8" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb2-9"><a href="#cb2-9" aria-hidden="true" tabindex="-1"></a><span class="fu">### Purpose</span></span>
|
||
<span id="cb2-10"><a href="#cb2-10" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb2-11"><a href="#cb2-11" aria-hidden="true" tabindex="-1"></a>Draft a concise, implementation‑ready Product Requirements Document (PRD) from a</span>
|
||
<span id="cb2-12"><a href="#cb2-12" aria-hidden="true" tabindex="-1"></a>one‑sentence feature description plus any additional Q&A with the stakeholder.</span>
|
||
<span id="cb2-13"><a href="#cb2-13" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb2-14"><a href="#cb2-14" aria-hidden="true" tabindex="-1"></a><span class="fu">### Output</span></span>
|
||
<span id="cb2-15"><a href="#cb2-15" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb2-16"><a href="#cb2-16" aria-hidden="true" tabindex="-1"></a>• Create /tasks/<span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/PRD.md • Markdown only – no prose, no code‑fences. •</span>
|
||
<span id="cb2-17"><a href="#cb2-17" aria-hidden="true" tabindex="-1"></a>File structure: # <span class="dt"><</span><span class="kw">Feature</span><span class="ot"> title</span><span class="dt">></span> ## 1. Problem / Motivation ## 2. Goals ## 3.</span>
|
||
<span id="cb2-18"><a href="#cb2-18" aria-hidden="true" tabindex="-1"></a>Non‑Goals ## 4. Target Users & Personas ## 5. User Stories (Gherkin</span>
|
||
<span id="cb2-19"><a href="#cb2-19" aria-hidden="true" tabindex="-1"></a>“Given/When/Then”) ## 6. Acceptance Criteria ## 7. Technical Notes /</span>
|
||
<span id="cb2-20"><a href="#cb2-20" aria-hidden="true" tabindex="-1"></a>Dependencies ## 8. Open Questions</span>
|
||
<span id="cb2-21"><a href="#cb2-21" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb2-22"><a href="#cb2-22" aria-hidden="true" tabindex="-1"></a><span class="fu">### Process</span></span>
|
||
<span id="cb2-23"><a href="#cb2-23" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb2-24"><a href="#cb2-24" aria-hidden="true" tabindex="-1"></a><span class="ss">1. </span>Stakeholder provides a single‑sentence feature idea and invokes this rule.</span>
|
||
<span id="cb2-25"><a href="#cb2-25" aria-hidden="true" tabindex="-1"></a><span class="ss">2. </span>Look at specifications in <span class="in">`specs/`</span> and inspect the code if needed to get an</span>
|
||
<span id="cb2-26"><a href="#cb2-26" aria-hidden="true" tabindex="-1"></a> idea what the Stakeholder expects from this feature.</span>
|
||
<span id="cb2-27"><a href="#cb2-27" aria-hidden="true" tabindex="-1"></a><span class="ss">3. </span>Ask up to five clarifying questions (Q1 … Q5). If anything is still vague</span>
|
||
<span id="cb2-28"><a href="#cb2-28" aria-hidden="true" tabindex="-1"></a> after five, look into the project with the new information provided. You may</span>
|
||
<span id="cb2-29"><a href="#cb2-29" aria-hidden="true" tabindex="-1"></a> ask for further clarification up to 3 times following this schema, else flag</span>
|
||
<span id="cb2-30"><a href="#cb2-30" aria-hidden="true" tabindex="-1"></a> it in _Open Questions_.</span>
|
||
<span id="cb2-31"><a href="#cb2-31" aria-hidden="true" tabindex="-1"></a><span class="ss">4. </span>After questions are answered reply exactly: Ready to generate the PRD.</span>
|
||
<span id="cb2-32"><a href="#cb2-32" aria-hidden="true" tabindex="-1"></a><span class="ss">5. </span>On a user message that contains only the word "go" (case‑insensitive): •</span>
|
||
<span id="cb2-33"><a href="#cb2-33" aria-hidden="true" tabindex="-1"></a> Generate /tasks/<span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/PRD.md following _Output_ spec. • Reply:</span>
|
||
<span id="cb2-34"><a href="#cb2-34" aria-hidden="true" tabindex="-1"></a> <span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/PRD.md created – review it.</span>
|
||
<span id="cb2-35"><a href="#cb2-35" aria-hidden="true" tabindex="-1"></a><span class="ss">6. </span>STOP. Do **not** generate tasks or code in this rule.</span>
|
||
<span id="cb2-36"><a href="#cb2-36" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb2-37"><a href="#cb2-37" aria-hidden="true" tabindex="-1"></a><span class="fu">### Writing guidelines</span></span>
|
||
<span id="cb2-38"><a href="#cb2-38" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb2-39"><a href="#cb2-39" aria-hidden="true" tabindex="-1"></a>• Keep each bullet ≤120 characters. • Use action verbs and measurable language.</span>
|
||
<span id="cb2-40"><a href="#cb2-40" aria-hidden="true" tabindex="-1"></a>• Leave TBDs only in _Open Questions_. • No business fluff – pretend the reader</span>
|
||
<span id="cb2-41"><a href="#cb2-41" aria-hidden="true" tabindex="-1"></a>is a junior developer.</span>
|
||
<span id="cb2-42"><a href="#cb2-42" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb2-43"><a href="#cb2-43" aria-hidden="true" tabindex="-1"></a><span class="fu">### Safety rails</span></span>
|
||
<span id="cb2-44"><a href="#cb2-44" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb2-45"><a href="#cb2-45" aria-hidden="true" tabindex="-1"></a>• Assume all work happens in a non‑production environment, unless otherwise</span>
|
||
<span id="cb2-46"><a href="#cb2-46" aria-hidden="true" tabindex="-1"></a>stated or requested by you. • Do not include sensitive data or credentials in</span>
|
||
<span id="cb2-47"><a href="#cb2-47" aria-hidden="true" tabindex="-1"></a>the PRD. • Check the generated Document with <span class="in">`markdownlint`</span> (if available),</span>
|
||
<span id="cb2-48"><a href="#cb2-48" aria-hidden="true" tabindex="-1"></a>apply auto-fixes and fix the remaining issues manually.</span></code><button title="In die Zwischenablage kopieren" class="code-copy-button"><i class="bi"></i></button></pre></div>
|
||
</div>
|
||
<p>A call to this rule usually looks like <code>@generate-prd We noticed, that …. Therefore investigate the codebase to come up with a PRD addressing these issues.</code>.</p>
|
||
</section>
|
||
<section id="specifications" class="level4 page-columns page-full">
|
||
<h4 class="anchored" data-anchor-id="specifications">Specifications</h4>
|
||
<div class="column-page-right">
|
||
<div class="sourceCode" id="cb3"><pre class="sourceCode markdown code-with-copy"><code class="sourceCode markdown"><span id="cb3-1"><a href="#cb3-1" aria-hidden="true" tabindex="-1"></a><span class="co">---</span></span>
|
||
<span id="cb3-2"><a href="#cb3-2" aria-hidden="true" tabindex="-1"></a><span class="an">description:</span><span class="co"> Specification Writing Guidelines</span></span>
|
||
<span id="cb3-3"><a href="#cb3-3" aria-hidden="true" tabindex="-1"></a><span class="an">globs:</span></span>
|
||
<span id="cb3-4"><a href="#cb3-4" aria-hidden="true" tabindex="-1"></a><span class="an">alwaysApply:</span><span class="co"> false</span></span>
|
||
<span id="cb3-5"><a href="#cb3-5" aria-hidden="true" tabindex="-1"></a><span class="co">---</span></span>
|
||
<span id="cb3-6"><a href="#cb3-6" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-7"><a href="#cb3-7" aria-hidden="true" tabindex="-1"></a><span class="fu"># Specification Writing Guidelines</span></span>
|
||
<span id="cb3-8"><a href="#cb3-8" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-9"><a href="#cb3-9" aria-hidden="true" tabindex="-1"></a><span class="fu">## Overview</span></span>
|
||
<span id="cb3-10"><a href="#cb3-10" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-11"><a href="#cb3-11" aria-hidden="true" tabindex="-1"></a>This rule provides guidelines for writing and maintaining specifications in</span>
|
||
<span id="cb3-12"><a href="#cb3-12" aria-hidden="true" tabindex="-1"></a><span class="co">[</span><span class="ot">specs/</span><span class="co">](mdc:specs)</span> to ensure consistency, clarity, and prevent implementation</span>
|
||
<span id="cb3-13"><a href="#cb3-13" aria-hidden="true" tabindex="-1"></a>discrepancies.</span>
|
||
<span id="cb3-14"><a href="#cb3-14" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-15"><a href="#cb3-15" aria-hidden="true" tabindex="-1"></a><span class="fu">## Specification Structure</span></span>
|
||
<span id="cb3-16"><a href="#cb3-16" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-17"><a href="#cb3-17" aria-hidden="true" tabindex="-1"></a><span class="fu">### Required Sections</span></span>
|
||
<span id="cb3-18"><a href="#cb3-18" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-19"><a href="#cb3-19" aria-hidden="true" tabindex="-1"></a>Every specification should include:</span>
|
||
<span id="cb3-20"><a href="#cb3-20" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-21"><a href="#cb3-21" aria-hidden="true" tabindex="-1"></a><span class="ss">1. </span>**Title and Purpose**</span>
|
||
<span id="cb3-22"><a href="#cb3-22" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-23"><a href="#cb3-23" aria-hidden="true" tabindex="-1"></a> <span class="in">```markdown</span></span>
|
||
<span id="cb3-24"><a href="#cb3-24" aria-hidden="true" tabindex="-1"></a> # Specification: <span class="co">[</span><span class="ot">Component Name</span><span class="co">]</span></span>
|
||
<span id="cb3-25"><a href="#cb3-25" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-26"><a href="#cb3-26" aria-hidden="true" tabindex="-1"></a> Brief description of what this specification covers and its purpose.</span>
|
||
<span id="cb3-27"><a href="#cb3-27" aria-hidden="true" tabindex="-1"></a> <span class="in">```</span></span>
|
||
<span id="cb3-28"><a href="#cb3-28" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-29"><a href="#cb3-29" aria-hidden="true" tabindex="-1"></a><span class="ss">2. </span>**Scope and Boundaries**</span>
|
||
<span id="cb3-30"><a href="#cb3-30" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-31"><a href="#cb3-31" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>What is included/excluded</span>
|
||
<span id="cb3-32"><a href="#cb3-32" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Dependencies on other specifications</span>
|
||
<span id="cb3-33"><a href="#cb3-33" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Relationship to other components</span>
|
||
<span id="cb3-34"><a href="#cb3-34" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-35"><a href="#cb3-35" aria-hidden="true" tabindex="-1"></a><span class="ss">3. </span>**Detailed Requirements**</span>
|
||
<span id="cb3-36"><a href="#cb3-36" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-37"><a href="#cb3-37" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Structured by logical sections</span>
|
||
<span id="cb3-38"><a href="#cb3-38" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Clear, unambiguous language</span>
|
||
<span id="cb3-39"><a href="#cb3-39" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Examples where helpful</span>
|
||
<span id="cb3-40"><a href="#cb3-40" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-41"><a href="#cb3-41" aria-hidden="true" tabindex="-1"></a><span class="ss">4. </span>**Error Handling**</span>
|
||
<span id="cb3-42"><a href="#cb3-42" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-43"><a href="#cb3-43" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>How errors should be handled</span>
|
||
<span id="cb3-44"><a href="#cb3-44" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Fallback behaviors</span>
|
||
<span id="cb3-45"><a href="#cb3-45" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Edge cases</span>
|
||
<span id="cb3-46"><a href="#cb3-46" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-47"><a href="#cb3-47" aria-hidden="true" tabindex="-1"></a><span class="ss">5. </span>**Testing Requirements**</span>
|
||
<span id="cb3-48"><a href="#cb3-48" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Expected test coverage</span>
|
||
<span id="cb3-49"><a href="#cb3-49" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Snapshot requirements</span>
|
||
<span id="cb3-50"><a href="#cb3-50" aria-hidden="true" tabindex="-1"></a><span class="ss"> - </span>Approval test criteria</span>
|
||
<span id="cb3-51"><a href="#cb3-51" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-52"><a href="#cb3-52" aria-hidden="true" tabindex="-1"></a><span class="fu">## Writing Standards</span></span>
|
||
<span id="cb3-53"><a href="#cb3-53" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-54"><a href="#cb3-54" aria-hidden="true" tabindex="-1"></a><span class="fu">### Clarity and Precision</span></span>
|
||
<span id="cb3-55"><a href="#cb3-55" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-56"><a href="#cb3-56" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Use specific language**: Avoid vague terms like "should" or "might"</span>
|
||
<span id="cb3-57"><a href="#cb3-57" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Provide examples**: Include concrete examples for complex requirements</span>
|
||
<span id="cb3-58"><a href="#cb3-58" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Define terms**: Clearly define any technical terms or concepts</span>
|
||
<span id="cb3-59"><a href="#cb3-59" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Use consistent formatting**: Follow established patterns from existing specs</span>
|
||
<span id="cb3-60"><a href="#cb3-60" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-61"><a href="#cb3-61" aria-hidden="true" tabindex="-1"></a><span class="fu">### Structure and Organization</span></span>
|
||
<span id="cb3-62"><a href="#cb3-62" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-63"><a href="#cb3-63" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Logical flow**: Organize sections in logical order</span>
|
||
<span id="cb3-64"><a href="#cb3-64" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Consistent headings**: Use consistent heading levels and naming</span>
|
||
<span id="cb3-65"><a href="#cb3-65" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Cross-references**: Link to related specifications using</span>
|
||
<span id="cb3-66"><a href="#cb3-66" aria-hidden="true" tabindex="-1"></a> <span class="in">`[spec_name](mdc:specs/spec_name.md)`</span></span>
|
||
<span id="cb3-67"><a href="#cb3-67" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Code blocks**: Use appropriate language tags for code examples</span>
|
||
<span id="cb3-68"><a href="#cb3-68" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-69"><a href="#cb3-69" aria-hidden="true" tabindex="-1"></a><span class="fu">### Completeness</span></span>
|
||
<span id="cb3-70"><a href="#cb3-70" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-71"><a href="#cb3-71" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Cover all cases**: Address normal, error, and edge cases</span>
|
||
<span id="cb3-72"><a href="#cb3-72" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Be exhaustive**: Don't assume implementation details</span>
|
||
<span id="cb3-73"><a href="#cb3-73" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Consider interactions**: How this spec relates to others</span>
|
||
<span id="cb3-74"><a href="#cb3-74" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Future-proof**: Consider potential changes and extensions</span>
|
||
<span id="cb3-75"><a href="#cb3-75" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-76"><a href="#cb3-76" aria-hidden="true" tabindex="-1"></a><span class="fu">## Specification Maintenance</span></span>
|
||
<span id="cb3-77"><a href="#cb3-77" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-78"><a href="#cb3-78" aria-hidden="true" tabindex="-1"></a><span class="fu">### Version Control</span></span>
|
||
<span id="cb3-79"><a href="#cb3-79" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-80"><a href="#cb3-80" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Update specs first**: When changing behavior, update spec before</span>
|
||
<span id="cb3-81"><a href="#cb3-81" aria-hidden="true" tabindex="-1"></a> implementation</span>
|
||
<span id="cb3-82"><a href="#cb3-82" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Document changes**: Use clear commit messages explaining spec changes</span>
|
||
<span id="cb3-83"><a href="#cb3-83" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Review process**: Have specs reviewed before implementation</span>
|
||
<span id="cb3-84"><a href="#cb3-84" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-85"><a href="#cb3-85" aria-hidden="true" tabindex="-1"></a><span class="fu">### Consistency Checks</span></span>
|
||
<span id="cb3-86"><a href="#cb3-86" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-87"><a href="#cb3-87" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Cross-reference validation**: Ensure all links to other specs are valid</span>
|
||
<span id="cb3-88"><a href="#cb3-88" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Terminology consistency**: Use consistent terms across all specs</span>
|
||
<span id="cb3-89"><a href="#cb3-89" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Format consistency**: Follow established formatting patterns</span>
|
||
<span id="cb3-90"><a href="#cb3-90" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-91"><a href="#cb3-91" aria-hidden="true" tabindex="-1"></a><span class="fu">### Testing Integration</span></span>
|
||
<span id="cb3-92"><a href="#cb3-92" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-93"><a href="#cb3-93" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Spec-driven tests**: Write tests based on specification requirements</span>
|
||
<span id="cb3-94"><a href="#cb3-94" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Snapshot validation**: Ensure snapshots match specification exactly</span>
|
||
<span id="cb3-95"><a href="#cb3-95" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Approval tests**: Use approval tests to catch spec violations</span>
|
||
<span id="cb3-96"><a href="#cb3-96" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-97"><a href="#cb3-97" aria-hidden="true" tabindex="-1"></a><span class="fu">## Quality Checklist</span></span>
|
||
<span id="cb3-98"><a href="#cb3-98" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-99"><a href="#cb3-99" aria-hidden="true" tabindex="-1"></a><span class="fu">### Before Finalizing Specification</span></span>
|
||
<span id="cb3-100"><a href="#cb3-100" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-101"><a href="#cb3-101" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> All requirements clearly stated</span>
|
||
<span id="cb3-102"><a href="#cb3-102" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Examples provided for complex requirements</span>
|
||
<span id="cb3-103"><a href="#cb3-103" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Error cases covered</span>
|
||
<span id="cb3-104"><a href="#cb3-104" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Cross-references to other specs included</span>
|
||
<span id="cb3-105"><a href="#cb3-105" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Out of scope items clearly defined</span>
|
||
<span id="cb3-106"><a href="#cb3-106" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Testing requirements specified</span>
|
||
<span id="cb3-107"><a href="#cb3-107" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Consistent formatting throughout</span>
|
||
<span id="cb3-108"><a href="#cb3-108" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Check the generated Document with <span class="in">`markdownlint`</span> (if available), apply</span>
|
||
<span id="cb3-109"><a href="#cb3-109" aria-hidden="true" tabindex="-1"></a> auto-fixes and fix the remaining issues manually.</span>
|
||
<span id="cb3-110"><a href="#cb3-110" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-111"><a href="#cb3-111" aria-hidden="true" tabindex="-1"></a><span class="fu">### Review Criteria</span></span>
|
||
<span id="cb3-112"><a href="#cb3-112" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-113"><a href="#cb3-113" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Is the specification unambiguous?</span>
|
||
<span id="cb3-114"><a href="#cb3-114" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Are all edge cases covered?</span>
|
||
<span id="cb3-115"><a href="#cb3-115" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Does it integrate well with other specs?</span>
|
||
<span id="cb3-116"><a href="#cb3-116" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Is it testable?</span>
|
||
<span id="cb3-117"><a href="#cb3-117" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="va">[ ]</span> Is it maintainable?</span>
|
||
<span id="cb3-118"><a href="#cb3-118" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-119"><a href="#cb3-119" aria-hidden="true" tabindex="-1"></a><span class="fu">## Common Pitfalls to Avoid</span></span>
|
||
<span id="cb3-120"><a href="#cb3-120" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-121"><a href="#cb3-121" aria-hidden="true" tabindex="-1"></a><span class="fu">### Ambiguity</span></span>
|
||
<span id="cb3-122"><a href="#cb3-122" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-123"><a href="#cb3-123" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Vague language**: "The system should handle errors gracefully"</span>
|
||
<span id="cb3-124"><a href="#cb3-124" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Missing details**: Not specifying exact error handling behavior</span>
|
||
<span id="cb3-125"><a href="#cb3-125" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Unclear relationships**: Not explaining how components interact</span>
|
||
<span id="cb3-126"><a href="#cb3-126" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-127"><a href="#cb3-127" aria-hidden="true" tabindex="-1"></a><span class="fu">### Inconsistency</span></span>
|
||
<span id="cb3-128"><a href="#cb3-128" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-129"><a href="#cb3-129" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Different terms**: Using different terms for the same concept</span>
|
||
<span id="cb3-130"><a href="#cb3-130" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Inconsistent formatting**: Not following established patterns</span>
|
||
<span id="cb3-131"><a href="#cb3-131" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Conflicting requirements**: Requirements that contradict other specs</span>
|
||
<span id="cb3-132"><a href="#cb3-132" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-133"><a href="#cb3-133" aria-hidden="true" tabindex="-1"></a><span class="fu">### Incompleteness</span></span>
|
||
<span id="cb3-134"><a href="#cb3-134" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-135"><a href="#cb3-135" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Missing edge cases**: Not considering unusual scenarios</span>
|
||
<span id="cb3-136"><a href="#cb3-136" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Incomplete examples**: Examples that don't cover all cases</span>
|
||
<span id="cb3-137"><a href="#cb3-137" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Missing error handling**: Not specifying what happens when things go wrong</span>
|
||
<span id="cb3-138"><a href="#cb3-138" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-139"><a href="#cb3-139" aria-hidden="true" tabindex="-1"></a><span class="fu">## Related Rules</span></span>
|
||
<span id="cb3-140"><a href="#cb3-140" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb3-141"><a href="#cb3-141" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="co">[</span><span class="ot">spec-compliance-investigation.mdc</span><span class="co">](mdc:.cursor/rules/spec-compliance-investigation.mdc)</span></span>
|
||
<span id="cb3-142"><a href="#cb3-142" aria-hidden="true" tabindex="-1"></a> How to investigate spec-implementation discrepancies</span>
|
||
<span id="cb3-143"><a href="#cb3-143" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span><span class="co">[</span><span class="ot">base_overview.mdc</span><span class="co">](mdc:.cursor/rules/base_overview.mdc)</span> Project structure and</span>
|
||
<span id="cb3-144"><a href="#cb3-144" aria-hidden="true" tabindex="-1"></a> conventions</span></code><button title="In die Zwischenablage kopieren" class="code-copy-button"><i class="bi"></i></button></pre></div>
|
||
</div>
|
||
<p>As it is obvious this is a very intricate rule with many criteria. For this you really <strong>need</strong> a reasoning and deep-thinking model that can also reason for extended times (many minutes are normal!) and call tools every now and then to get even more information. Models like <code>o3</code>, <code>deepseek-r1</code> and the <code>opus</code>-series of <code>claude</code> really shine here.</p>
|
||
</section>
|
||
<section id="spec-compliance" class="level4 page-columns page-full">
|
||
<h4 class="anchored" data-anchor-id="spec-compliance">Spec Compliance</h4>
|
||
<div class="column-page-right">
|
||
<div class="sourceCode" id="cb4"><pre class="sourceCode markdown code-with-copy"><code class="sourceCode markdown"><span id="cb4-1"><a href="#cb4-1" aria-hidden="true" tabindex="-1"></a><span class="co">---</span></span>
|
||
<span id="cb4-2"><a href="#cb4-2" aria-hidden="true" tabindex="-1"></a><span class="an">description:</span><span class="co"> Spec Compliance Investigation Guide</span></span>
|
||
<span id="cb4-3"><a href="#cb4-3" aria-hidden="true" tabindex="-1"></a><span class="an">globs:</span></span>
|
||
<span id="cb4-4"><a href="#cb4-4" aria-hidden="true" tabindex="-1"></a><span class="an">alwaysApply:</span><span class="co"> false</span></span>
|
||
<span id="cb4-5"><a href="#cb4-5" aria-hidden="true" tabindex="-1"></a><span class="co">---</span></span>
|
||
<span id="cb4-6"><a href="#cb4-6" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-7"><a href="#cb4-7" aria-hidden="true" tabindex="-1"></a><span class="fu"># Spec Compliance Investigation Guide</span></span>
|
||
<span id="cb4-8"><a href="#cb4-8" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-9"><a href="#cb4-9" aria-hidden="true" tabindex="-1"></a><span class="fu">## Overview</span></span>
|
||
<span id="cb4-10"><a href="#cb4-10" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-11"><a href="#cb4-11" aria-hidden="true" tabindex="-1"></a>This rule provides a systematic approach for investigating discrepancies between</span>
|
||
<span id="cb4-12"><a href="#cb4-12" aria-hidden="true" tabindex="-1"></a>specifications and implementations, following the pattern established. Do not</span>
|
||
<span id="cb4-13"><a href="#cb4-13" aria-hidden="true" tabindex="-1"></a>change any code during this phase.</span>
|
||
<span id="cb4-14"><a href="#cb4-14" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-15"><a href="#cb4-15" aria-hidden="true" tabindex="-1"></a><span class="fu">## Investigation Process</span></span>
|
||
<span id="cb4-16"><a href="#cb4-16" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-17"><a href="#cb4-17" aria-hidden="true" tabindex="-1"></a><span class="fu">### 1. Initial Analysis</span></span>
|
||
<span id="cb4-18"><a href="#cb4-18" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-19"><a href="#cb4-19" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Locate specification**: Find the relevant spec file in <span class="co">[</span><span class="ot">specs/</span><span class="co">](mdc:specs)</span></span>
|
||
<span id="cb4-20"><a href="#cb4-20" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Identify implementation**: Find corresponding source code in <span class="co">[</span><span class="ot">src/</span><span class="co">](mdc:src)</span></span>
|
||
<span id="cb4-21"><a href="#cb4-21" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Check tests**: Review test files in <span class="co">[</span><span class="ot">tests/</span><span class="co">](mdc:tests)</span> for expected</span>
|
||
<span id="cb4-22"><a href="#cb4-22" aria-hidden="true" tabindex="-1"></a> behavior</span>
|
||
<span id="cb4-23"><a href="#cb4-23" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>**Run tests**: Execute <span class="in">`poetry run pytest`</span> to identify current failures</span>
|
||
<span id="cb4-24"><a href="#cb4-24" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-25"><a href="#cb4-25" aria-hidden="true" tabindex="-1"></a><span class="fu">### 2. Systematic Comparison</span></span>
|
||
<span id="cb4-26"><a href="#cb4-26" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-27"><a href="#cb4-27" aria-hidden="true" tabindex="-1"></a>For each specification section:</span>
|
||
<span id="cb4-28"><a href="#cb4-28" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-29"><a href="#cb4-29" aria-hidden="true" tabindex="-1"></a><span class="ss">1. </span>**Extract requirements** from spec file</span>
|
||
<span id="cb4-30"><a href="#cb4-30" aria-hidden="true" tabindex="-1"></a><span class="ss">2. </span>**Examine implementation** in source code</span>
|
||
<span id="cb4-31"><a href="#cb4-31" aria-hidden="true" tabindex="-1"></a><span class="ss">3. </span>**Compare outputs** with test snapshots</span>
|
||
<span id="cb4-32"><a href="#cb4-32" aria-hidden="true" tabindex="-1"></a><span class="ss">4. </span>**Document discrepancies** with specific examples</span>
|
||
<span id="cb4-33"><a href="#cb4-33" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-34"><a href="#cb4-34" aria-hidden="true" tabindex="-1"></a><span class="fu">### 3. Documentation Structure</span></span>
|
||
<span id="cb4-35"><a href="#cb4-35" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-36"><a href="#cb4-36" aria-hidden="true" tabindex="-1"></a>Create analysis document in <span class="co">[</span><span class="ot">tmp/spec\_[component]\_discrepancies.md</span><span class="co">](mdc:tmp/)</span></span>
|
||
<span id="cb4-37"><a href="#cb4-37" aria-hidden="true" tabindex="-1"></a>with:</span>
|
||
<span id="cb4-38"><a href="#cb4-38" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-39"><a href="#cb4-39" aria-hidden="true" tabindex="-1"></a><span class="in">```markdown</span></span>
|
||
<span id="cb4-40"><a href="#cb4-40" aria-hidden="true" tabindex="-1"></a><span class="fu"># [Component] Specification vs Implementation Discrepancies</span></span>
|
||
<span id="cb4-41"><a href="#cb4-41" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-42"><a href="#cb4-42" aria-hidden="true" tabindex="-1"></a><span class="fu">## Executive Summary</span></span>
|
||
<span id="cb4-43"><a href="#cb4-43" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-44"><a href="#cb4-44" aria-hidden="true" tabindex="-1"></a>Brief overview of findings and impact</span>
|
||
<span id="cb4-45"><a href="#cb4-45" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-46"><a href="#cb4-46" aria-hidden="true" tabindex="-1"></a><span class="fu">## Key Discrepancies Found</span></span>
|
||
<span id="cb4-47"><a href="#cb4-47" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-48"><a href="#cb4-48" aria-hidden="true" tabindex="-1"></a><span class="fu">### 1. [Category] - [Specific Issue]</span></span>
|
||
<span id="cb4-49"><a href="#cb4-49" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-50"><a href="#cb4-50" aria-hidden="true" tabindex="-1"></a>**Specification:**</span>
|
||
<span id="cb4-51"><a href="#cb4-51" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-52"><a href="#cb4-52" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Requirement details</span>
|
||
<span id="cb4-53"><a href="#cb4-53" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-54"><a href="#cb4-54" aria-hidden="true" tabindex="-1"></a>**Implementation:**</span>
|
||
<span id="cb4-55"><a href="#cb4-55" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-56"><a href="#cb4-56" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Current behavior</span>
|
||
<span id="cb4-57"><a href="#cb4-57" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>✅ Correct aspects</span>
|
||
<span id="cb4-58"><a href="#cb4-58" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>❌ Incorrect aspects</span>
|
||
<span id="cb4-59"><a href="#cb4-59" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-60"><a href="#cb4-60" aria-hidden="true" tabindex="-1"></a><span class="fu">## Test Results</span></span>
|
||
<span id="cb4-61"><a href="#cb4-61" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-62"><a href="#cb4-62" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Current test failures</span>
|
||
<span id="cb4-63"><a href="#cb4-63" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Output differences</span>
|
||
<span id="cb4-64"><a href="#cb4-64" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-65"><a href="#cb4-65" aria-hidden="true" tabindex="-1"></a><span class="fu">## Impact Assessment</span></span>
|
||
<span id="cb4-66"><a href="#cb4-66" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-67"><a href="#cb4-67" aria-hidden="true" tabindex="-1"></a><span class="fu">### High Impact Issues:</span></span>
|
||
<span id="cb4-68"><a href="#cb4-68" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-69"><a href="#cb4-69" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Critical functionality problems</span>
|
||
<span id="cb4-70"><a href="#cb4-70" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>User experience issues</span>
|
||
<span id="cb4-71"><a href="#cb4-71" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-72"><a href="#cb4-72" aria-hidden="true" tabindex="-1"></a><span class="fu">### Medium Impact Issues:</span></span>
|
||
<span id="cb4-73"><a href="#cb4-73" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-74"><a href="#cb4-74" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Consistency problems</span>
|
||
<span id="cb4-75"><a href="#cb4-75" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Formatting issues</span>
|
||
<span id="cb4-76"><a href="#cb4-76" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-77"><a href="#cb4-77" aria-hidden="true" tabindex="-1"></a><span class="fu">### Low Impact Issues:</span></span>
|
||
<span id="cb4-78"><a href="#cb4-78" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-79"><a href="#cb4-79" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Minor differences</span>
|
||
<span id="cb4-80"><a href="#cb4-80" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Style variations</span>
|
||
<span id="cb4-81"><a href="#cb4-81" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-82"><a href="#cb4-82" aria-hidden="true" tabindex="-1"></a><span class="fu">## Recommendations</span></span>
|
||
<span id="cb4-83"><a href="#cb4-83" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-84"><a href="#cb4-84" aria-hidden="true" tabindex="-1"></a><span class="fu">### Option 1: Update Spec to Follow Code</span></span>
|
||
<span id="cb4-85"><a href="#cb4-85" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-86"><a href="#cb4-86" aria-hidden="true" tabindex="-1"></a>**What to change:**</span>
|
||
<span id="cb4-87"><a href="#cb4-87" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-88"><a href="#cb4-88" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Specific spec modifications</span>
|
||
<span id="cb4-89"><a href="#cb4-89" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-90"><a href="#cb4-90" aria-hidden="true" tabindex="-1"></a>**Pros:**</span>
|
||
<span id="cb4-91"><a href="#cb4-91" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-92"><a href="#cb4-92" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Benefits of this approach</span>
|
||
<span id="cb4-93"><a href="#cb4-93" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-94"><a href="#cb4-94" aria-hidden="true" tabindex="-1"></a>**Cons:**</span>
|
||
<span id="cb4-95"><a href="#cb4-95" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-96"><a href="#cb4-96" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Drawbacks of this approach</span>
|
||
<span id="cb4-97"><a href="#cb4-97" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-98"><a href="#cb4-98" aria-hidden="true" tabindex="-1"></a><span class="fu">### Option 2: Update Code to Follow Spec</span></span>
|
||
<span id="cb4-99"><a href="#cb4-99" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-100"><a href="#cb4-100" aria-hidden="true" tabindex="-1"></a>**What to change:**</span>
|
||
<span id="cb4-101"><a href="#cb4-101" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-102"><a href="#cb4-102" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Specific code modifications</span>
|
||
<span id="cb4-103"><a href="#cb4-103" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-104"><a href="#cb4-104" aria-hidden="true" tabindex="-1"></a>**Pros:**</span>
|
||
<span id="cb4-105"><a href="#cb4-105" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-106"><a href="#cb4-106" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Benefits of this approach</span>
|
||
<span id="cb4-107"><a href="#cb4-107" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-108"><a href="#cb4-108" aria-hidden="true" tabindex="-1"></a>**Cons:**</span>
|
||
<span id="cb4-109"><a href="#cb4-109" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-110"><a href="#cb4-110" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Drawbacks of this approach</span>
|
||
<span id="cb4-111"><a href="#cb4-111" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-112"><a href="#cb4-112" aria-hidden="true" tabindex="-1"></a><span class="fu">### Option 3: Recommended Hybrid Approach</span></span>
|
||
<span id="cb4-113"><a href="#cb4-113" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-114"><a href="#cb4-114" aria-hidden="true" tabindex="-1"></a>**Recommended Solution:**</span>
|
||
<span id="cb4-115"><a href="#cb4-115" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-116"><a href="#cb4-116" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Phased implementation plan</span>
|
||
<span id="cb4-117"><a href="#cb4-117" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-118"><a href="#cb4-118" aria-hidden="true" tabindex="-1"></a>**Rationale:**</span>
|
||
<span id="cb4-119"><a href="#cb4-119" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-120"><a href="#cb4-120" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Why this approach is best</span>
|
||
<span id="cb4-121"><a href="#cb4-121" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-122"><a href="#cb4-122" aria-hidden="true" tabindex="-1"></a>**Implementation Priority:**</span>
|
||
<span id="cb4-123"><a href="#cb4-123" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-124"><a href="#cb4-124" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Immediate, short-term, medium-term tasks</span>
|
||
<span id="cb4-125"><a href="#cb4-125" aria-hidden="true" tabindex="-1"></a><span class="in">```</span></span>
|
||
<span id="cb4-126"><a href="#cb4-126" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-127"><a href="#cb4-127" aria-hidden="true" tabindex="-1"></a><span class="in">## Quality Checklist</span></span>
|
||
<span id="cb4-128"><a href="#cb4-128" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-129"><a href="#cb4-129" aria-hidden="true" tabindex="-1"></a><span class="in">### Before Finalizing Investigation</span></span>
|
||
<span id="cb4-130"><a href="#cb4-130" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-131"><a href="#cb4-131" aria-hidden="true" tabindex="-1"></a><span class="in">- [ ] All specification sections reviewed</span></span>
|
||
<span id="cb4-132"><a href="#cb4-132" aria-hidden="true" tabindex="-1"></a><span class="in">- [ ] Implementation code thoroughly examined</span></span>
|
||
<span id="cb4-133"><a href="#cb4-133" aria-hidden="true" tabindex="-1"></a><span class="in">- [ ] Tests run and failures documented</span></span>
|
||
<span id="cb4-134"><a href="#cb4-134" aria-hidden="true" tabindex="-1"></a><span class="in">- [ ] Impact assessment completed</span></span>
|
||
<span id="cb4-135"><a href="#cb4-135" aria-hidden="true" tabindex="-1"></a><span class="in">- [ ] All three solution options evaluated</span></span>
|
||
<span id="cb4-136"><a href="#cb4-136" aria-hidden="true" tabindex="-1"></a><span class="in">- [ ] Recommendation justified with rationale</span></span>
|
||
<span id="cb4-137"><a href="#cb4-137" aria-hidden="true" tabindex="-1"></a><span class="in">- [ ] Implementation plan prioritized</span></span>
|
||
<span id="cb4-138"><a href="#cb4-138" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-139"><a href="#cb4-139" aria-hidden="true" tabindex="-1"></a><span class="in">### Documentation Quality</span></span>
|
||
<span id="cb4-140"><a href="#cb4-140" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-141"><a href="#cb4-141" aria-hidden="true" tabindex="-1"></a><span class="in">- [ ] Specific examples provided for each discrepancy</span></span>
|
||
<span id="cb4-142"><a href="#cb4-142" aria-hidden="true" tabindex="-1"></a><span class="in">- [ ] Code snippets included where relevant</span></span>
|
||
<span id="cb4-143"><a href="#cb4-143" aria-hidden="true" tabindex="-1"></a><span class="in">- [ ] Pros/cons clearly articulated</span></span>
|
||
<span id="cb4-144"><a href="#cb4-144" aria-hidden="true" tabindex="-1"></a><span class="in">- [ ] Implementation steps detailed</span></span>
|
||
<span id="cb4-145"><a href="#cb4-145" aria-hidden="true" tabindex="-1"></a><span class="in">- [ ] Priority levels assigned</span></span>
|
||
<span id="cb4-146"><a href="#cb4-146" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-147"><a href="#cb4-147" aria-hidden="true" tabindex="-1"></a><span class="in">## Related Rules</span></span>
|
||
<span id="cb4-148"><a href="#cb4-148" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb4-149"><a href="#cb4-149" aria-hidden="true" tabindex="-1"></a><span class="in">- [Base Project Overview](mdc:.cursor/rules/base-project-overview.mdc) Project</span></span>
|
||
<span id="cb4-150"><a href="#cb4-150" aria-hidden="true" tabindex="-1"></a><span class="in"> structure and conventions</span></span>
|
||
<span id="cb4-151"><a href="#cb4-151" aria-hidden="true" tabindex="-1"></a><span class="in">- [Spec Guidelines](mdc:.cursor/rules/spec-guidelines.mdc) How to write</span></span>
|
||
<span id="cb4-152"><a href="#cb4-152" aria-hidden="true" tabindex="-1"></a><span class="in"> specifications</span></span></code><button title="In die Zwischenablage kopieren" class="code-copy-button"><i class="bi"></i></button></pre></div>
|
||
</div>
|
||
<p>This compliance-report also need a deep-thinking model, like the specification beforehand.</p>
|
||
</section>
|
||
<section id="tasks" class="level4 page-columns page-full">
|
||
<h4 class="anchored" data-anchor-id="tasks">Tasks</h4>
|
||
<div class="column-page-right">
|
||
<div class="sourceCode" id="cb5"><pre class="sourceCode markdown code-with-copy"><code class="sourceCode markdown"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="co">---</span></span>
|
||
<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="an">description:</span></span>
|
||
<span id="cb5-3"><a href="#cb5-3" aria-hidden="true" tabindex="-1"></a><span class="an">globs:</span></span>
|
||
<span id="cb5-4"><a href="#cb5-4" aria-hidden="true" tabindex="-1"></a><span class="an">alwaysApply:</span><span class="co"> false</span></span>
|
||
<span id="cb5-5"><a href="#cb5-5" aria-hidden="true" tabindex="-1"></a><span class="co">---</span></span>
|
||
<span id="cb5-6"><a href="#cb5-6" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb5-7"><a href="#cb5-7" aria-hidden="true" tabindex="-1"></a><span class="fu">## Task List creation</span></span>
|
||
<span id="cb5-8"><a href="#cb5-8" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb5-9"><a href="#cb5-9" aria-hidden="true" tabindex="-1"></a><span class="fu">### Purpose</span></span>
|
||
<span id="cb5-10"><a href="#cb5-10" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb5-11"><a href="#cb5-11" aria-hidden="true" tabindex="-1"></a>Translate a Product Requirements Document (PRD) into an executable Markdown task</span>
|
||
<span id="cb5-12"><a href="#cb5-12" aria-hidden="true" tabindex="-1"></a>list that a junior developer (human or AI) can follow without extra context.</span>
|
||
<span id="cb5-13"><a href="#cb5-13" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb5-14"><a href="#cb5-14" aria-hidden="true" tabindex="-1"></a><span class="fu">### Output</span></span>
|
||
<span id="cb5-15"><a href="#cb5-15" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb5-16"><a href="#cb5-16" aria-hidden="true" tabindex="-1"></a>• Create /tasks/<span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/TASKS.md (overwrite if it exists). • Markdown only, no</span>
|
||
<span id="cb5-17"><a href="#cb5-17" aria-hidden="true" tabindex="-1"></a>prose around it. • Epics = H2 headings (<span class="in">`## 1. <Epic>`</span>). • Tasks = unchecked</span>
|
||
<span id="cb5-18"><a href="#cb5-18" aria-hidden="true" tabindex="-1"></a>check‑boxes (<span class="in">`- [ ] 1.1 <task>`</span>). • Sub‑tasks = indent one space under their</span>
|
||
<span id="cb5-19"><a href="#cb5-19" aria-hidden="true" tabindex="-1"></a>parent (<span class="in">` - [ ] 1.1.1 <subtask>`</span>). • Create a</span>
|
||
<span id="cb5-20"><a href="#cb5-20" aria-hidden="true" tabindex="-1"></a>/tasks/<span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/Task*<Epic>*<span class="dt"><</span><span class="kw">task</span><span class="dt">></span><span class="sc">\_</span><span class="dt"><</span><span class="kw">subtask</span><span class="dt">></span>.md (i.e. <span class="in">`Task_3_2_4.md`</span> for Epic</span>
|
||
<span id="cb5-21"><a href="#cb5-21" aria-hidden="true" tabindex="-1"></a>3, Task 2, Subtask 4)</span>
|
||
<span id="cb5-22"><a href="#cb5-22" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb5-23"><a href="#cb5-23" aria-hidden="true" tabindex="-1"></a><span class="fu">### Process</span></span>
|
||
<span id="cb5-24"><a href="#cb5-24" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb5-25"><a href="#cb5-25" aria-hidden="true" tabindex="-1"></a><span class="ss">1. </span>Read the tagged PRD.</span>
|
||
<span id="cb5-26"><a href="#cb5-26" aria-hidden="true" tabindex="-1"></a><span class="ss">2. </span>**Investigate** the current state of the repository to collect answers to</span>
|
||
<span id="cb5-27"><a href="#cb5-27" aria-hidden="true" tabindex="-1"></a> your first questions. All specs for fixed behaviours and outputs are located</span>
|
||
<span id="cb5-28"><a href="#cb5-28" aria-hidden="true" tabindex="-1"></a> in <span class="in">`specs/`</span>. **Consult those** as a source first before trying to</span>
|
||
<span id="cb5-29"><a href="#cb5-29" aria-hidden="true" tabindex="-1"></a> reverse-engineer from the code. </span>
|
||
<span id="cb5-30"><a href="#cb5-30" aria-hidden="true" tabindex="-1"></a> If specs are in need of change then this is also a task to be generated.</span>
|
||
<span id="cb5-31"><a href="#cb5-31" aria-hidden="true" tabindex="-1"></a><span class="ss">3. </span>If critical info is missing and cannot be answered by looking at the code,</span>
|
||
<span id="cb5-32"><a href="#cb5-32" aria-hidden="true" tabindex="-1"></a> ask max five clarifying questions (Q1 … Q5) and stop until answered.</span>
|
||
<span id="cb5-33"><a href="#cb5-33" aria-hidden="true" tabindex="-1"></a><span class="ss">4. </span>After questions are answered think about the answers and: Either: look at the</span>
|
||
<span id="cb5-34"><a href="#cb5-34" aria-hidden="true" tabindex="-1"></a> code again, then goto 3., and ask for further clarification Or: Reply</span>
|
||
<span id="cb5-35"><a href="#cb5-35" aria-hidden="true" tabindex="-1"></a> exactly: Ready to generate the subtasks – respond **go** to proceed.</span>
|
||
<span id="cb5-36"><a href="#cb5-36" aria-hidden="true" tabindex="-1"></a><span class="ss">5. </span>On a user message that contains only the word "go" (case‑insensitive): a.</span>
|
||
<span id="cb5-37"><a href="#cb5-37" aria-hidden="true" tabindex="-1"></a> Generate /tasks/<span class="dt"><</span><span class="kw">feature</span><span class="dt">></span>/TASKS.md following _Output_ spec. b. Reply with:</span>
|
||
<span id="cb5-38"><a href="#cb5-38" aria-hidden="true" tabindex="-1"></a> TASKS.md created – review them.</span>
|
||
<span id="cb5-39"><a href="#cb5-39" aria-hidden="true" tabindex="-1"></a><span class="ss">6. </span>After TASKS.md was reviewed, create <span class="in">`Task_<e>_<t>_<s>.md`</span> for each task and</span>
|
||
<span id="cb5-40"><a href="#cb5-40" aria-hidden="true" tabindex="-1"></a> subtask containing implementation hints like relevant specs (link them!),</span>
|
||
<span id="cb5-41"><a href="#cb5-41" aria-hidden="true" tabindex="-1"></a> primary files to edit/review for this task, tests needing change, etc.</span>
|
||
<span id="cb5-42"><a href="#cb5-42" aria-hidden="true" tabindex="-1"></a><span class="ss">7. </span>Stop. Do **not** begin executing tasks in this rule.</span>
|
||
<span id="cb5-43"><a href="#cb5-43" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb5-44"><a href="#cb5-44" aria-hidden="true" tabindex="-1"></a><span class="fu">### Writing guidelines</span></span>
|
||
<span id="cb5-45"><a href="#cb5-45" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb5-46"><a href="#cb5-46" aria-hidden="true" tabindex="-1"></a>• Each item ≤120 characters, start with an action verb. • Hints are allowed</span>
|
||
<span id="cb5-47"><a href="#cb5-47" aria-hidden="true" tabindex="-1"></a>below each item as HTML-Comment and do not count against the 120 characters. •</span>
|
||
<span id="cb5-48"><a href="#cb5-48" aria-hidden="true" tabindex="-1"></a>Group related work into logical epics with ≤7 direct child items. • Prefer</span>
|
||
<span id="cb5-49"><a href="#cb5-49" aria-hidden="true" tabindex="-1"></a>concrete file paths, commands, specs or APIs when available. • Skip</span>
|
||
<span id="cb5-50"><a href="#cb5-50" aria-hidden="true" tabindex="-1"></a>implementation details obvious from the codebase in the overview. • If a task</span>
|
||
<span id="cb5-51"><a href="#cb5-51" aria-hidden="true" tabindex="-1"></a>only concerns up to 5 files, name them in the detailed file. Otherwise give</span>
|
||
<span id="cb5-52"><a href="#cb5-52" aria-hidden="true" tabindex="-1"></a>hints on how to search for them (i.e. "everything under src/models/").</span>
|
||
<span id="cb5-53"><a href="#cb5-53" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb5-54"><a href="#cb5-54" aria-hidden="true" tabindex="-1"></a><span class="fu">### Safety rails</span></span>
|
||
<span id="cb5-55"><a href="#cb5-55" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb5-56"><a href="#cb5-56" aria-hidden="true" tabindex="-1"></a>• Never touch production data. • Assume all work happens in a feature branch,</span>
|
||
<span id="cb5-57"><a href="#cb5-57" aria-hidden="true" tabindex="-1"></a>never commit directly to main. • Check the generated Document with</span>
|
||
<span id="cb5-58"><a href="#cb5-58" aria-hidden="true" tabindex="-1"></a><span class="in">`markdownlint`</span> (if available), apply auto-fixes and fix the remaining issues</span>
|
||
<span id="cb5-59"><a href="#cb5-59" aria-hidden="true" tabindex="-1"></a>manually.</span></code><button title="In die Zwischenablage kopieren" class="code-copy-button"><i class="bi"></i></button></pre></div>
|
||
</div>
|
||
<p>This also works better with one of those deep-thinking models.</p>
|
||
</section>
|
||
<section id="other-rules" class="level4">
|
||
<h4 class="anchored" data-anchor-id="other-rules">Other Rules</h4>
|
||
<p>I have some other rules with guidelines on how to write proper tests, one for “just follow the tasks in TASKS.md one by one until done with commit after each task”, etc. Those are omitted for brevity. Also they are so simple, that non-reasoning-models can follow them. Cheap <code>claude3-sonnet</code> or small, specialised coding-LLMs are enough to get the job done with this preparation.</p>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
<section id="example-rules-in-action" class="level2 page-columns page-full">
|
||
<h2 class="anchored" data-anchor-id="example-rules-in-action">Example: Rules in Action</h2>
|
||
<p>The codebase we look at here is a project called <code>gitlab_overviewer</code>. It takes gitlab-api-keys and generates nice overviews for tracking metadata in different projects across different groups. With a nice export to markdown (for rendering in gitlab itself) and quarto (for exporting to i.e. confluence) with multiple pages etc. pp.</p>
|
||
<p>The current issue is, that due to a complete rewrite we are happy with the current output, but there are some minor problems still remaining. Some of them may also due to specs being incorrect, because requirements or ideas changed over time.</p>
|
||
<section id="analyzing-the-situation" class="level3 page-columns page-full">
|
||
<h3 class="anchored">Analyzing the situation</h3>
|
||
<p>For the analysis <code>o3</code> was used and it was sufficient on first try. Here is (part of) the conversation:</p>
|
||
<div class="callout callout-style-default callout-tip callout-titled">
|
||
<div class="callout-header d-flex align-content-center">
|
||
<div class="callout-icon-container">
|
||
<i class="callout-icon"></i>
|
||
</div>
|
||
<div class="callout-title-container flex-fill">
|
||
User
|
||
</div>
|
||
</div>
|
||
<div class="callout-body-container callout-body">
|
||
<p><code>@spec-compliance-investigation.mdc</code> do a spec-compliance investigation on <code>@spec_renderer_markdown.md</code> . The relevant modules in the <code>@/src</code> <strong>should</strong> link to the spec (omissions are possible and also out-of-spec).</p>
|
||
</div>
|
||
</div>
|
||
<div class="quarto-figure quarto-figure-center">
|
||
<figure class="figure">
|
||
<p><a href="images/initial_analysis.png" class="lightbox" data-gallery="quarto-lightbox-gallery-1" title="The initial analysis with most thinking steps opened. It is interesting to see the agent collect needed information onthe first try and generates a lot of ‘thought’."><img src="images/initial_analysis.png" class="img-fluid figure-img" alt="The initial analysis with most thinking steps opened. It is interesting to see the agent collect needed information onthe first try and generates a lot of ‘thought’."></a></p>
|
||
<figcaption>The initial analysis with most thinking steps opened. It is interesting to see the agent collect needed information onthe first try and generates a lot of ‘thought’.</figcaption>
|
||
</figure>
|
||
</div>
|
||
<div class="column-page-right">
|
||
<div class="callout callout-style-default callout-note callout-titled">
|
||
<div class="callout-header d-flex align-content-center">
|
||
<div class="callout-icon-container">
|
||
<i class="callout-icon"></i>
|
||
</div>
|
||
<div class="callout-title-container flex-fill">
|
||
Cursor
|
||
</div>
|
||
</div>
|
||
<div class="callout-body-container callout-body">
|
||
<p>tmp/spec_renderer_markdown_discrepancies.md:</p>
|
||
<blockquote class="blockquote">
|
||
<h1 id="markdown-renderer-specification-vs-implementation-discrepancies">Markdown Renderer Specification vs Implementation Discrepancies</h1>
|
||
<h2 id="executive-summary" class="anchored" data-anchor-id="analyzing-the-situation">Executive Summary</h2>
|
||
<p>The current <code>render_grouped_markdown</code> implementation provides most of the layout and structural requirements defined in <code>specs/spec_renderer_markdown.md</code>. However, several key aspects diverge from the specification, leading to failing approval tests and user-visible issues. The most critical problems concern ordering guarantees and the content chosen for the <em>Description</em> callout.</p>
|
||
<h2 id="key-discrepancies-found" class="anchored">Key Discrepancies Found</h2>
|
||
<h3 id="ordering-projects-inside-detailed-sections" class="anchored">1. Ordering – Projects inside detailed sections</h3>
|
||
<p><strong>Specification:</strong></p>
|
||
<ul>
|
||
<li>Projects in the detailed part <em>“appear in the same order they had inside their group’s summary table”</em> (Spec §4, bullet 3).</li>
|
||
</ul>
|
||
<p><strong>Implementation:</strong></p>
|
||
<div class="sourceCode" id="cb6"><pre class="sourceCode python code-with-copy"><code class="sourceCode python"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="co"># ... excerpt ...</span></span>
|
||
<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="cf">for</span> od <span class="kw">in</span> <span class="bu">sorted</span>(group_projects, key<span class="op">=</span><span class="kw">lambda</span> p: p.project.name.lower()):</span>
|
||
<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a> <span class="co"># renders project sections alphabetically</span></span></code><button title="In die Zwischenablage kopieren" class="code-copy-button"><i class="bi"></i></button></pre></div>
|
||
<ul>
|
||
<li>Projects are sorted <strong>alphabetically</strong>, not in the original summary-table order.</li>
|
||
<li>✅ Groups themselves are ordered by descending project count (matches spec).</li>
|
||
<li>❌ Project order within groups breaks the “mirror the incoming, already-sorted data” rule.</li>
|
||
</ul>
|
||
<h3 id="description-callout-picks-raw-front-matter-if-no-description-key-exists" class="anchored">2. <em>Description</em> callout picks raw front-matter if no <code>description</code> key exists</h3>
|
||
<p><strong>Specification:</strong></p>
|
||
<ul>
|
||
<li>If front-matter contains a <code>description</code> key → use its value (callout-type <code>tip</code>).</li>
|
||
<li>Else if <code>Readme.content</code> is not empty → use that content (callout-type <code>warning</code>).</li>
|
||
<li><code>Readme.content</code> is defined as the <strong>first real paragraph without front-matter</strong> (see Model spec).</li>
|
||
</ul>
|
||
<p><strong>Implementation:</strong></p>
|
||
<ul>
|
||
<li>Correctly checks for <code>.raw_frontmatter["description"]</code> first ⬆️.</li>
|
||
<li>Then falls back to <code>od.readme.content</code> unconditionally. In practice many fixture READMEs still include <code>--- …</code> YAML because the pre-processing step did <strong>not</strong> strip it, so the callout now contains the entire front-matter block – cf. failing snapshot diff lines starting with <code>> --- "author":</code>.</li>
|
||
<li>✅ Callout types (<code>tip</code>/<code>warning</code>/<code>danger</code>) are chosen per spec.</li>
|
||
<li>❌ Content for the warning variant violates the “no raw front-matter” expectation and visual quality.</li>
|
||
</ul>
|
||
<p>8< ……… 8<</p>
|
||
<h2 id="test-results" class="anchored">Test Results</h2>
|
||
<pre><code>poetry run pytest -q → 5 failures / 119 passed
|
||
• tests/rendering/test_markdown_renderer_approval.py (output mismatch)
|
||
• tests/rendering/test_quarto_renderer_approval.py (cascade – shares ordering logic)
|
||
• tests/models/test_model_invariants.py (3 failures unrelated to renderer)</code></pre>
|
||
<p>The Markdown approval diff highlights exactly the two major discrepancies above (alphabetical ordering & raw front-matter in callout).</p>
|
||
<h2 id="impact-assessment" class="anchored">Impact Assessment</h2>
|
||
<h3 id="high-impact-issues" class="anchored">High Impact Issues</h3>
|
||
<ol type="1">
|
||
<li><strong>Incorrect project ordering</strong> – breaks reproducibility guarantees and user expectations; also propagates to Quarto renderer.</li>
|
||
<li><strong>Raw YAML in description callout</strong> – severely harms readability of generated documentation.</li>
|
||
</ol>
|
||
<h3 id="medium-impact-issues" class="anchored">Medium Impact Issues</h3>
|
||
<ul>
|
||
<li>None identified besides cosmetic phrasing.</li>
|
||
</ul>
|
||
<h3 id="low-impact-issues" class="anchored">Low Impact Issues</h3>
|
||
<ul>
|
||
<li>Minor stylistic deviations (e.g., spacing) appear compliant within tolerance.</li>
|
||
</ul>
|
||
<h2 id="recommendations" class="anchored">Recommendations</h2>
|
||
<h3 id="option-1-update-spec-to-follow-code" class="anchored">Option 1: Update Spec to Follow Code</h3>
|
||
<p><strong>What to change:</strong></p>
|
||
<ul>
|
||
<li>Relax ordering requirement to alphabetical order.</li>
|
||
<li>Allow raw front-matter YAML in description callout.</li>
|
||
</ul>
|
||
<p><strong>Pros:</strong> No code changes; quick test green.</p>
|
||
<p><strong>Cons:</strong> Violates original design intent; exposes low-level data to end-users; poor UX.</p>
|
||
<h3 id="option-2-update-code-to-follow-spec-preferred" class="anchored">Option 2: Update Code to Follow Spec (preferred)</h3>
|
||
<p><strong>What to change:</strong></p>
|
||
<ol type="1">
|
||
<li>Remove the <code>sorted(...)</code> call to preserve input ordering.</li>
|
||
<li>Ensure <code>Readme.content</code> truly excludes YAML front-matter (use <code>parse_readme</code> during data ingestion or strip before rendering).</li>
|
||
</ol>
|
||
<p><strong>Pros:</strong> Restores spec fidelity; fixes approval tests; better documentation quality.</p>
|
||
<p><strong>Cons:</strong> Requires code edit & possibly data-loading adjustments.</p>
|
||
<h3 id="option-3-hybrid-approach" class="anchored">Option 3: Hybrid Approach</h3>
|
||
<ul>
|
||
<li>Fix ordering in renderer.</li>
|
||
<li>Keep current fallback but truncate front-matter to first paragraph until improved extraction available.</li>
|
||
</ul>
|
||
<p><strong>Recommended Solution:</strong> <strong>Option 2</strong> – small, well-scoped patches bring implementation back in line with spec and tests.</p>
|
||
<p><strong>Implementation Priority:</strong></p>
|
||
<ul>
|
||
<li>Immediate: ordering fix & front-matter stripping.</li>
|
||
<li>Short-term: add regression tests for ordering.</li>
|
||
<li>Medium-term: audit other renderers (Quarto) for same issues.</li>
|
||
</ul>
|
||
</blockquote>
|
||
<p>I have completed the investigation phase and produced a detailed report at</p>
|
||
<pre class="text"><code>tmp/spec_renderer_markdown_discrepancies.md</code></pre>
|
||
<p>Key take-aways:</p>
|
||
<p>• Two core deviations from the Markdown-renderer spec were found</p>
|
||
<ol type="1">
|
||
<li>Project ordering in the detailed section is alphabetical instead of mirroring the summary order.</li>
|
||
<li>When a README lacks a <code>description:</code> key, the <em>Description</em> call-out falls back to raw front-matter, so YAML blocks are rendered verbatim.</li>
|
||
</ol>
|
||
<p>• These issues are the root cause of the failing approval tests.</p>
|
||
<p>• A concise impact assessment and three solution options are documented; the recommended path is to fix the code to match the specification.</p>
|
||
<p>Let me know if you’d like to proceed with the recommended fixes or explore the alternate options.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
<section id="correcting-the-analysis" class="level3 page-columns page-full">
|
||
<h3 class="anchored">Correcting the analysis</h3>
|
||
<p>By reading the analysis i soon noticed, that things were missing out of the spec. So i added a bit of text:</p>
|
||
<div class="callout callout-style-default callout-warning callout-titled">
|
||
<div class="callout-header d-flex align-content-center">
|
||
<div class="callout-icon-container">
|
||
<i class="callout-icon"></i>
|
||
</div>
|
||
<div class="callout-title-container flex-fill">
|
||
Commenting the result
|
||
</div>
|
||
</div>
|
||
<div class="callout-body-container callout-body">
|
||
<section id="ordering-projects-inside-detailed-sections-1" class="level3">
|
||
<h3 class="anchored" data-anchor-id="ordering-projects-inside-detailed-sections-1">1. Ordering – Projects inside detailed sections</h3>
|
||
<p><strong>Specification:</strong> > […snip…]</p>
|
||
<ul>
|
||
<li>❌ Project order within groups breaks the “mirror the incoming, already-sorted data” rule.</li>
|
||
</ul>
|
||
<p><strong>Comment:</strong></p>
|
||
<ul>
|
||
<li>The implemented behaviour is using alphabetical order in the <strong>detailed</strong> section and in the table according to the sort defined in the <code>@spec_table_config</code> . The spec needs updating.</li>
|
||
</ul>
|
||
</section>
|
||
<section id="description-callout-picks-raw-front-matter-if-no-description-key-exists-1" class="level3">
|
||
<h3 class="anchored" data-anchor-id="description-callout-picks-raw-front-matter-if-no-description-key-exists-1">2. <em>Description</em> callout picks raw front-matter if no <code>description</code> key exists</h3>
|
||
<p><strong>Specification:</strong> > […snip…]</p>
|
||
<ul>
|
||
<li>❌ Content for the warning variant violates the “no raw front-matter” expectation and visual quality.</li>
|
||
</ul>
|
||
<p><strong>Comment:</strong></p>
|
||
<ul>
|
||
<li>This is a violation of spec. But additionally it should only render the first 10 lines of <code>Readme.content</code> and then add a <code>…continues…</code> if there are more lines.</li>
|
||
</ul>
|
||
</section>
|
||
</div>
|
||
</div>
|
||
<p>Armed with those correction i told the LLM to generate better recommendations, that align with my goals. The LLM then deleted the whole recommendations-section and wrote exactly what i wanted. Again <code>o3</code> was used for the slow and deep thinking.</p>
|
||
<div class="callout callout-style-default callout-tip callout-titled">
|
||
<div class="callout-header d-flex align-content-center">
|
||
<div class="callout-icon-container">
|
||
<i class="callout-icon"></i>
|
||
</div>
|
||
<div class="callout-title-container flex-fill">
|
||
User
|
||
</div>
|
||
</div>
|
||
<div class="callout-body-container callout-body">
|
||
<p>I added comments to the part that are not up to spec. Update the recommendations in <code>@spec_renderer_markdown_discrepancies.md</code> according to those comments.</p>
|
||
</div>
|
||
</div>
|
||
<div class="quarto-figure quarto-figure-center page-columns page-full">
|
||
<figure class="figure page-columns page-full">
|
||
<p><a href="images/thoughts_after_commenting.png" class="lightbox" data-gallery="quarto-lightbox-gallery-2" title="Thoughts of the agent after i updated the comments. It always feels good to read that i was understood by the machine."><img src="images/thoughts_after_commenting.png" class="img-fluid figure-img" alt="Thoughts of the agent after i updated the comments. It always feels good to read that i was understood by the machine."></a></p>
|
||
<figcaption>Thoughts of the agent after i updated the comments. It always feels good to read that i was understood<a href="#fn3" class="footnote-ref" id="fnref3" role="doc-noteref"><sup>3</sup></a> by the machine.</figcaption>
|
||
<div class="no-row-height column-margin column-container"><div id="fn3"><p><sup>3</sup> yaya .. i know. Antropomorphing an AI.</p></div></div></figure>
|
||
</div>
|
||
<div class="column-page-right">
|
||
<div class="callout callout-style-default callout-note callout-titled">
|
||
<div class="callout-header d-flex align-content-center">
|
||
<div class="callout-icon-container">
|
||
<i class="callout-icon"></i>
|
||
</div>
|
||
<div class="callout-title-container flex-fill">
|
||
Cursor
|
||
</div>
|
||
</div>
|
||
<div class="callout-body-container callout-body">
|
||
<p>tmp/spec_renderer_markdown_discrepancies.md:</p>
|
||
<blockquote class="blockquote">
|
||
<p>// … existing code …</p>
|
||
<h2 id="recommendations-1" class="anchored" data-anchor-id="correcting-the-analysis">Recommendations</h2>
|
||
<h3 id="option-a-align-specification-with-current-ordering-preferred" class="anchored">Option A: Align Specification with Current Ordering (preferred)</h3>
|
||
<p><strong>What to change:</strong></p>
|
||
<ol type="1">
|
||
<li>Amend <code>spec_renderer_markdown.md</code> §4 to state that <em>projects in the detailed section appear alphabetically by project name</em>. This legitimises the current implementation and removes the ordering-related approval failure.</li>
|
||
<li>Keep the existing implementation for project ordering unchanged.</li>
|
||
<li><strong>Change the renderer implementation for the <em>Description</em> call-out</strong>:
|
||
<ul>
|
||
<li>Strip YAML front-matter from <code>Readme.content</code> (use <code>parse_readme</code>).</li>
|
||
<li>Render <strong>at most the first 10 non-empty lines</strong> of the resulting text.</li>
|
||
<li>If more lines remain, append a marker <code>…continues…</code> as the final line inside the call-out.</li>
|
||
</ul></li>
|
||
<li>Add corresponding wording to the spec clarifying the 10-line truncation rule.</li>
|
||
</ol>
|
||
<p><strong>Pros:</strong></p>
|
||
<ul>
|
||
<li>Least intrusive to working behaviour users already rely on.</li>
|
||
<li>Fixes readability issue without reordering content.</li>
|
||
<li>Smaller diff in test fixtures (only call-out content).</li>
|
||
</ul>
|
||
<p><strong>Cons:</strong></p>
|
||
<ul>
|
||
<li>Requires a spec update (but that is a documentation-only task).</li>
|
||
</ul>
|
||
<h3 id="option-b-keep-original-spec-ordering-change-code" class="anchored">Option B: Keep Original Spec Ordering, Change Code</h3>
|
||
<p><strong>What to change:</strong></p>
|
||
<ol type="1">
|
||
<li>Remove <code>sorted()</code> so project order mirrors summary-table order.</li>
|
||
<li>Apply the same <em>Description</em> call-out improvements as in Option A.</li>
|
||
</ol>
|
||
<p><strong>Pros:</strong></p>
|
||
<ul>
|
||
<li>Upholds original design intent of summary/detailed symmetry.</li>
|
||
</ul>
|
||
<p><strong>Cons:</strong></p>
|
||
<ul>
|
||
<li>Generates a larger diff for existing artefacts; may surprise current users.</li>
|
||
</ul>
|
||
<h3 id="recommended-solution" class="anchored">Recommended Solution</h3>
|
||
<p>Proceed with <strong>Option A</strong>:</p>
|
||
<ul>
|
||
<li>Update the specification paragraph on ordering.</li>
|
||
<li>Implement the 10-line truncation + <code>…continues…</code> logic in the renderer.</li>
|
||
</ul>
|
||
<h3 id="implementation-priority" class="anchored">Implementation Priority</h3>
|
||
<ol type="1">
|
||
<li>Immediate: implement call-out truncation logic & adjust approval snapshots.</li>
|
||
<li>Immediate: update Markdown renderer spec for alphabetical ordering and call-out truncation.</li>
|
||
<li>Short-term: add regression tests for the new truncation rule.</li>
|
||
<li>Medium-term: propagate the truncation rule to the Quarto renderer to keep output parity. // … existing code …</li>
|
||
</ol>
|
||
</blockquote>
|
||
<p>The “Recommendations” section has been rewritten to reflect your comments:</p>
|
||
<p>1. Ordering: keep the current alphabetical behaviour and adjust the spec instead.<br>
|
||
2. Description call-out: implement a 10-line preview with a “…continues…” marker after stripping front-matter.</p>
|
||
<p>These points are now captured as <strong>Option A (preferred)</strong>, with a revised implementation roadmap.</p>
|
||
<p>Let me know when you’d like me to start on the code/spec changes.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
<section id="creating-tasks" class="level3 page-columns page-full">
|
||
<h3 class="anchored">Creating Tasks</h3>
|
||
<p>Now that we have a clear plan without touching any code, lets flesh out the Details.</p>
|
||
<div class="callout callout-style-default callout-tip callout-titled">
|
||
<div class="callout-header d-flex align-content-center">
|
||
<div class="callout-icon-container">
|
||
<i class="callout-icon"></i>
|
||
</div>
|
||
<div class="callout-title-container flex-fill">
|
||
User
|
||
</div>
|
||
</div>
|
||
<div class="callout-body-container callout-body">
|
||
<p><code>@generate-tasks.mdc</code> generate Tasks for Option A of <code>@spec_renderer_markdown_discrepancies.md</code> under a feature called “markdown_rendering”.</p>
|
||
</div>
|
||
</div>
|
||
<div class="column-page-right">
|
||
<div class="callout callout-style-default callout-note callout-titled">
|
||
<div class="callout-header d-flex align-content-center">
|
||
<div class="callout-icon-container">
|
||
<i class="callout-icon"></i>
|
||
</div>
|
||
<div class="callout-title-container flex-fill">
|
||
Cursor
|
||
</div>
|
||
</div>
|
||
<div class="callout-body-container callout-body">
|
||
<p>TASKS.md:</p>
|
||
<blockquote class="blockquote">
|
||
<h2 id="spec-updates" class="anchored" data-anchor-id="creating-tasks">1. Spec updates</h2>
|
||
<ul class="task-list">
|
||
<li><label><input type="checkbox">1.1 Amend alphabetical ordering rule in <code>specs/spec_renderer_markdown.md</code></label></li>
|
||
<li><label><input type="checkbox">1.2 Document 10-line truncation rule for <em>Description</em> call-out</label></li>
|
||
</ul>
|
||
<h2 id="markdown-renderer-implementation" class="anchored">2. Markdown renderer implementation</h2>
|
||
<ul class="task-list">
|
||
<li><label><input type="checkbox">2.1 Strip YAML front-matter before rendering description</label>
|
||
<ul class="task-list">
|
||
<li><label><input type="checkbox">2.1.1 Invoke <code>parse_readme</code> to obtain cleaned content</label></li>
|
||
<li><label><input type="checkbox">2.1.2 Add unit test ensuring YAML is absent in call-out</label></li>
|
||
</ul></li>
|
||
<li><label><input type="checkbox">2.2 Truncate description to first 10 lines with <code>…continues…</code></label>
|
||
<ul class="task-list">
|
||
<li><label><input type="checkbox">2.2.1 Implement truncation logic in <code>render_grouped_markdown</code></label></li>
|
||
<li><label><input type="checkbox">2.2.2 Update approval snapshot for Overview.md</label></li>
|
||
</ul></li>
|
||
<li><label><input type="checkbox">2.3 Verify alphabetical ordering comment references spec</label></li>
|
||
</ul>
|
||
<h2 id="quarto-renderer-alignment" class="anchored">3. Quarto renderer alignment</h2>
|
||
<ul class="task-list">
|
||
<li><label><input type="checkbox">3.1 Port truncation & YAML-stripping logic to <code>src/gitlab_overviewer/rendering/quarto.py</code></label></li>
|
||
<li><label><input type="checkbox">3.2 Refresh Quarto renderer snapshot & tests</label></li>
|
||
</ul>
|
||
<h2 id="tests-snapshots" class="anchored">4. Tests & snapshots</h2>
|
||
<ul class="task-list">
|
||
<li><label><input type="checkbox">4.1 Update Markdown renderer approval snapshot after changes</label></li>
|
||
<li><label><input type="checkbox">4.2 Update Quarto renderer snapshot after changes</label></li>
|
||
<li><label><input type="checkbox">4.3 Add regression test for 10-line truncation rule</label></li>
|
||
</ul>
|
||
<h2 id="documentation-housekeeping" class="anchored">5. Documentation & housekeeping</h2>
|
||
<ul class="task-list">
|
||
<li><label><input type="checkbox">5.1 Run <code>markdownlint</code> and fix issues in updated docs/specs</label></li>
|
||
<li><label><input type="checkbox">5.2 Add entry to <code>CHANGELOG.md</code> under <em>Unreleased</em></label></li>
|
||
</ul>
|
||
</blockquote>
|
||
<p>Task_1_1.md:</p>
|
||
<blockquote class="blockquote">
|
||
<h3 id="task-1.1-amend-alphabetical-ordering-rule-in-spec_renderer_markdown.md" class="anchored">Task 1.1 – Amend alphabetical ordering rule in spec_renderer_markdown.md</h3>
|
||
<p><strong>Relevant spec:</strong> <code>specs/spec_renderer_markdown.md</code> (§4 Ordering Guarantees)</p>
|
||
<p><strong>Goal:</strong> Replace the bullet <em>“projects appear in the same order they had inside their group’s summary table”</em> with <em>“projects appear alphabetically by their name”</em>.</p>
|
||
<p><strong>Primary files:</strong></p>
|
||
<ul>
|
||
<li><code>specs/spec_renderer_markdown.md</code></li>
|
||
</ul>
|
||
<p><strong>Hints:</strong></p>
|
||
<ul>
|
||
<li>Search for the existing ordering clause (§4 bullet 3) and update accordingly.</li>
|
||
<li>Run <code>markdownlint</code> after editing: <code>npx markdownlint-cli2 specs/spec_renderer_markdown.md --fix</code>.</li>
|
||
</ul>
|
||
</blockquote>
|
||
<p>Task_1_2.md:</p>
|
||
<blockquote class="blockquote">
|
||
<h3 id="task-1.2-document-10-line-truncation-rule-for-description-call-out" class="anchored">Task 1.2 – Document 10-line truncation rule for Description call-out</h3>
|
||
<p><strong>Relevant spec:</strong> <code>specs/spec_renderer_markdown.md</code> (§3 Project Detail Sections)</p>
|
||
<p><strong>Goal:</strong> Add a subsection clarifying that when the <em>Description</em> call-out uses <code>Readme.content</code>, the renderer must:</p>
|
||
<ol type="1">
|
||
<li>Strip YAML front-matter.</li>
|
||
<li>Render the first 10 non-empty lines.</li>
|
||
<li>Append <code>…continues…</code> if more content was omitted.</li>
|
||
</ol>
|
||
<p><strong>Primary files:</strong></p>
|
||
<ul>
|
||
<li><code>specs/spec_renderer_markdown.md</code></li>
|
||
</ul>
|
||
<p><strong>Hints:</strong></p>
|
||
<ul>
|
||
<li>Place this clarification right after rule 3.1 in §3.</li>
|
||
<li>Provide a small Markdown example block.</li>
|
||
<li>Remember to update any cross-links.</li>
|
||
</ul>
|
||
</blockquote>
|
||
<p>[…further tasks omitted for brevity…]</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</section>
|
||
<section id="executing" class="level3 page-columns page-full">
|
||
<h3 class="anchored" data-anchor-id="executing">Executing</h3>
|
||
<p>With all that detailed instructions changes to the code are narrowly focused and the changes are easily reviewable. Execution does not need any deep thinking and can be done by a fast and cheap code-model like <code>gemini-2.5</code>, <code>claude3-sonnet</code>, etc.</p>
|
||
<p>They usually just loads all relevant files as context, work step-by-step, verify, tick off the task and report back for review.</p>
|
||
<div class="callout callout-style-default callout-tip callout-titled">
|
||
<div class="callout-header d-flex align-content-center">
|
||
<div class="callout-icon-container">
|
||
<i class="callout-icon"></i>
|
||
</div>
|
||
<div class="callout-title-container flex-fill">
|
||
User
|
||
</div>
|
||
</div>
|
||
<div class="callout-body-container callout-body">
|
||
<p><code>@xxx-work-on-tasks.mdc</code> <code>@/markdown_rendering</code> Implement all Task<em>1</em>\*.md.</p>
|
||
</div>
|
||
</div>
|
||
<div class="column-page-right">
|
||
<div class="callout callout-style-default callout-note callout-titled">
|
||
<div class="callout-header d-flex align-content-center">
|
||
<div class="callout-icon-container">
|
||
<i class="callout-icon"></i>
|
||
</div>
|
||
<div class="callout-title-container flex-fill">
|
||
Cursor
|
||
</div>
|
||
</div>
|
||
<div class="callout-body-container callout-body">
|
||
<p>I’ll help you implement the tasks from Task<em>1</em>*.md in the markdown rendering feature. Let me first check what these tasks entail.</p>
|
||
<p>Let me first check the current state of the spec file we need to modify.</p>
|
||
<p>I’ll now implement both tasks. Let’s start with Task 1.1 - amending the alphabetical ordering rule.</p>
|
||
<div class="sourceCode" id="cb9"><pre class="sourceCode markdown code-with-copy"><code class="sourceCode markdown"><span id="cb9-1"><a href="#cb9-1" aria-hidden="true" tabindex="-1"></a>// ... existing code ...</span>
|
||
<span id="cb9-2"><a href="#cb9-2" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb9-3"><a href="#cb9-3" aria-hidden="true" tabindex="-1"></a><span class="fu">## 4. Ordering Guarantees</span></span>
|
||
<span id="cb9-4"><a href="#cb9-4" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb9-5"><a href="#cb9-5" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Groups are ordered by the number of Projects rendered (alphabetically on a</span>
|
||
<span id="cb9-6"><a href="#cb9-6" aria-hidden="true" tabindex="-1"></a> tie).</span>
|
||
<span id="cb9-7"><a href="#cb9-7" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>Summary project order mirror the incoming, already-sorted data (see</span>
|
||
<span id="cb9-8"><a href="#cb9-8" aria-hidden="true" tabindex="-1"></a> <span class="co">[</span><span class="ot">Table Sorting</span><span class="co">](./spec_table_sorting.md)</span>).</span>
|
||
<span id="cb9-9"><a href="#cb9-9" aria-hidden="true" tabindex="-1"></a><span class="ss">- </span>In the detailed part, projects appear alphabetically by their name.</span>
|
||
<span id="cb9-10"><a href="#cb9-10" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb9-11"><a href="#cb9-11" aria-hidden="true" tabindex="-1"></a>// ... existing code ...</span></code><button title="In die Zwischenablage kopieren" class="code-copy-button"><i class="bi"></i></button></pre></div>
|
||
<p>Now let’s implement Task 1.2 - documenting the 10-line truncation rule for the Description call-out.</p>
|
||
<div class="sourceCode" id="cb10"><pre class="sourceCode markdown code-with-copy"><code class="sourceCode markdown"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a>// ... existing code ...</span>
|
||
<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a>Missing entries from the Project-Info are omitted.</span>
|
||
<span id="cb10-4"><a href="#cb10-4" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb10-5"><a href="#cb10-5" aria-hidden="true" tabindex="-1"></a>When using <span class="in">`Readme.content`</span> in a Description call-out, the renderer must:</span>
|
||
<span id="cb10-6"><a href="#cb10-6" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb10-7"><a href="#cb10-7" aria-hidden="true" tabindex="-1"></a><span class="in">```markdown</span></span>
|
||
<span id="cb10-8"><a href="#cb10-8" aria-hidden="true" tabindex="-1"></a><span class="ss">1. </span>Strip any YAML front-matter from the content</span>
|
||
<span id="cb10-9"><a href="#cb10-9" aria-hidden="true" tabindex="-1"></a><span class="ss">2. </span>Include only the first 10 non-empty lines</span>
|
||
<span id="cb10-10"><a href="#cb10-10" aria-hidden="true" tabindex="-1"></a><span class="ss">3. </span>If content was truncated, append "…continues…" on a new line</span>
|
||
<span id="cb10-11"><a href="#cb10-11" aria-hidden="true" tabindex="-1"></a><span class="in">```</span></span>
|
||
<span id="cb10-12"><a href="#cb10-12" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb10-13"><a href="#cb10-13" aria-hidden="true" tabindex="-1"></a><span class="in">Example:</span></span>
|
||
<span id="cb10-14"><a href="#cb10-14" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb10-15"><a href="#cb10-15" aria-hidden="true" tabindex="-1"></a><span class="in">```markdown</span></span>
|
||
<span id="cb10-16"><a href="#cb10-16" aria-hidden="true" tabindex="-1"></a><span class="in">> [!warning] Description</span></span>
|
||
<span id="cb10-17"><a href="#cb10-17" aria-hidden="true" tabindex="-1"></a><span class="in">></span></span>
|
||
<span id="cb10-18"><a href="#cb10-18" aria-hidden="true" tabindex="-1"></a><span class="in">> # My Project</span></span>
|
||
<span id="cb10-19"><a href="#cb10-19" aria-hidden="true" tabindex="-1"></a><span class="in">></span></span>
|
||
<span id="cb10-20"><a href="#cb10-20" aria-hidden="true" tabindex="-1"></a><span class="in">> This is a great project that does many things. It has multiple features:</span></span>
|
||
<span id="cb10-21"><a href="#cb10-21" aria-hidden="true" tabindex="-1"></a><span class="in">></span></span>
|
||
<span id="cb10-22"><a href="#cb10-22" aria-hidden="true" tabindex="-1"></a><span class="in">> - Feature 1</span></span>
|
||
<span id="cb10-23"><a href="#cb10-23" aria-hidden="true" tabindex="-1"></a><span class="in">> - Feature 2</span></span>
|
||
<span id="cb10-24"><a href="#cb10-24" aria-hidden="true" tabindex="-1"></a><span class="in">> - Feature 3</span></span>
|
||
<span id="cb10-25"><a href="#cb10-25" aria-hidden="true" tabindex="-1"></a><span class="in">> - Feature 4 …continues…</span></span>
|
||
<span id="cb10-26"><a href="#cb10-26" aria-hidden="true" tabindex="-1"></a><span class="in">```</span></span>
|
||
<span id="cb10-27"><a href="#cb10-27" aria-hidden="true" tabindex="-1"></a></span>
|
||
<span id="cb10-28"><a href="#cb10-28" aria-hidden="true" tabindex="-1"></a><span class="ss">2. </span>**Release badge** – image linking to <span class="in">`<web_url>/-/releases`</span>. // ...</span>
|
||
<span id="cb10-29"><a href="#cb10-29" aria-hidden="true" tabindex="-1"></a> existing code ...</span></code><button title="In die Zwischenablage kopieren" class="code-copy-button"><i class="bi"></i></button></pre></div>
|
||
<p>Let me run markdownlint as suggested in the task hints to ensure our changes meet the markdown style guidelines.</p>
|
||
<p>I’ve completed both tasks:</p>
|
||
<ol type="1">
|
||
<li>Task 1.1: Updated the ordering rule in section 4 to specify that projects appear alphabetically by their name in the detailed part, replacing the previous rule about maintaining summary table order.</li>
|
||
<li>Task 1.2: Added documentation about the Description call-out truncation rules after section 3.1, including:
|
||
<ul>
|
||
<li>The three required steps (strip YAML front-matter, render first 10 non-empty lines, append “…continues…”)</li>
|
||
<li>A clear example showing how the truncation should look</li>
|
||
</ul></li>
|
||
</ol>
|
||
<p>The markdownlint output shows some line length issues and a heading issue, but these appear to be pre-existing in the file and not related to our changes. The changes we made maintain the existing formatting style of the document.</p>
|
||
<p>Would you like me to address any of the markdownlint issues, or would you prefer to keep the changes focused on just implementing the two tasks?</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>And within 1 Minute everything was updated as expected and verified within a few seconds. Here you can really see the advantages of this approach. Instead of going off-track and focusing i.e. on fixing the <code>markdownlint</code>-issues<a href="#fn4" class="footnote-ref" id="fnref4" role="doc-noteref"><sup>4</sup></a> the agent notes that this is still an issue, but offers to keep focused on the tasks for the moment. With a simple ‘go’ i can continue tackle the next thing. 5 Minutes later everything is done and we have one less issue.</p>
|
||
<div class="no-row-height column-margin column-container"><div id="fn4"><p><sup>4</sup> As i have often expirienced with LLMs trying to be too perfect and pleasing the user without ever stopping</p></div></div></section>
|
||
</section>
|
||
<section id="result" class="level2 page-columns page-full">
|
||
<h2 class="anchored" data-anchor-id="result">Result</h2>
|
||
<p>In the fast-evolving field of AI-assisted software development, my experience with Cursor’s specification-driven workflow has yielded tangible outcomes:</p>
|
||
<ul>
|
||
<li><strong>Code Quality</strong>: By enforcing strict compliance checks and structured task creation, redundant code generation was reduced. The LLM still gets excited to “help”, but now it’s actually contributing meaningful changes instead of reinventing the wheel.</li>
|
||
<li><strong>Development Efficiency</strong>: The PRD-first approach has cut try&error time significantly. Before, getting the things i wanted was hit&miss. Now i “read the agents mind” and correct it during specification-creation.</li>
|
||
<li><strong>Project Integrity</strong>: Through rigorous spec adherence and systematic task breakdown, the codebase is more consistent, much better documented and decently tested<a href="#fn5" class="footnote-ref" id="fnref5" role="doc-noteref"><sup>5</sup></a>.</li>
|
||
<li><strong>Reduced Cognitive Load</strong>: The Cursor rule system has made it easier to focus on actual development tasks instead of wrestling with the AI’s sometimes questionable assumptions - or just installing a third different testing framework for exactly this module.</li>
|
||
</ul>
|
||
<div class="no-row-height column-margin column-container"><div id="fn5"><p><sup>5</sup> You know.. noone likes writing tests - and the person writing the code should never write the tests anyway. If you haven’t thought of something while coding, chanches are, that you miss that edge-case during testing as well.</p></div></div><p>In this <code>gitlab_overviewer</code> case study, i tried to show at an easy example, that this method works and <em>can</em> yields great outcomes. Even small discrepancies in the codebase tend to pop up during spec-reviews (which can be automated!). Next up would be running those in some kind of CI-job and integrating tools like issue-tracking into the agent instead of simple markdown-files in the repository as makeshift issue-tracker. But not by me for the forseeable future, so if you are looking for a project, feel free!</p>
|
||
<p><strong>All in all this isn’t a silver bullet for all AI-assisted development problems, but it’s made my coding experience with Cursor much more productive and predictable. It turns out treating an AI as a slightly overeager junior developer who needs clear instructions works better than hoping it’ll just “do the right thing”.</strong></p>
|
||
|
||
|
||
|
||
</section>
|
||
|
||
|
||
<div id="quarto-appendix" class="default"><section class="quarto-appendix-contents" role="doc-bibliography" id="quarto-bibliography"><h2 class="anchored quarto-appendix-heading">Literatur</h2><div id="refs" class="references csl-bib-body" data-entry-spacing="0" role="list">
|
||
<div id="ref-DeepSeek-AI2025DeepSeekR1IncentivizingReasoning" class="csl-entry" role="listitem">
|
||
<div class="csl-left-margin">1. </div><div class="csl-right-inline">DeepSeek-AI, Daya Guo, Dejian Yang, Haowei Zhang, Junxiao Song, Ruoyu Zhang, Runxin Xu, u. a. 2025. <span>DeepSeek-R1</span>: <span>Incentivizing Reasoning Capability</span> in <span>LLMs</span> via <span>Reinforcement Learning</span>. <a href="https://doi.org/10.48550/arXiv.2501.12948">https://doi.org/10.48550/arXiv.2501.12948</a>. Januar 22.</div>
|
||
</div>
|
||
<div id="ref-Shao2025SpuriousRewardsRethinking" class="csl-entry" role="listitem">
|
||
<div class="csl-left-margin">2. </div><div class="csl-right-inline">Shao, Rulin, Shuyue Stella Li, Rui Xin, Scott Geng, Yiping Wang, Sewoong Oh, Simon Shaolei Du, u. a. 2025. Spurious <span>Rewards</span>: <span>Rethinking Training Signals</span> in <span>RLVR</span>. <a href="https://doi.org/10.48550/arXiv.2506.10947">https://doi.org/10.48550/arXiv.2506.10947</a>. Juni 12.</div>
|
||
</div>
|
||
<div id="ref-bycloud2025LLMsRLRevelation" class="csl-entry" role="listitem">
|
||
<div class="csl-left-margin">3. </div><div class="csl-right-inline"><em><a href="https://www.youtube.com/watch?v=z3awgfU4yno">The <span>LLM</span>’s <span>RL Revelation We Didn</span>’t <span>See Coming</span></a></em>. 2025.</div>
|
||
</div>
|
||
<div id="ref-Liu2025UnderstandingR1ZeroLikeTraining" class="csl-entry" role="listitem">
|
||
<div class="csl-left-margin">4. </div><div class="csl-right-inline">Liu, Zichen, Changyu Chen, Wenjun Li, Penghui Qi, Tianyu Pang, Chao Du, Wee Sun Lee, und Min Lin. 2025. Understanding <span>R1-Zero-Like Training</span>: <span>A Critical Perspective</span>. <a href="https://doi.org/10.48550/arXiv.2503.20783">https://doi.org/10.48550/arXiv.2503.20783</a>. März 26.</div>
|
||
</div>
|
||
<div id="ref-Mukherjee2025ReinforcementLearningFinetunes" class="csl-entry" role="listitem">
|
||
<div class="csl-left-margin">5. </div><div class="csl-right-inline">Mukherjee, Sagnik, Lifan Yuan, Dilek Hakkani-Tur, und Hao Peng. 2025. Reinforcement <span>Learning Finetunes Small Subnetworks</span> in <span>Large Language Models</span>. <a href="https://doi.org/10.48550/arXiv.2505.11711">https://doi.org/10.48550/arXiv.2505.11711</a>. Mai 16.</div>
|
||
</div>
|
||
</div></section><section class="quarto-appendix-contents" id="quarto-citation"><h2 class="anchored quarto-appendix-heading">Zitat</h2><div><div class="quarto-appendix-secondary-label">Mit BibTeX zitieren:</div><pre class="sourceCode code-with-copy quarto-appendix-bibtex"><code class="sourceCode bibtex">@online{dresselhaus2025,
|
||
author = {Dresselhaus, Nicole},
|
||
title = {Field Report: Coding in the Age of AI with Cursor},
|
||
date = {2025-06-26},
|
||
url = {https://drezil.de/Writing/coding-age-ai.html},
|
||
langid = {de},
|
||
abstract = {This report presents practical methodologies and best
|
||
practices for developing software using Cursor, an AI-assisted IDE.
|
||
The paper details a structured workflow that emphasizes
|
||
specification-driven development, comprehensive documentation
|
||
practices, and systematic task management to maintain quality
|
||
control when working with language models. Through detailed examples
|
||
and rule configurations, it demonstrates how to leverage AI
|
||
capabilities while mitigating common pitfalls such as redundant code
|
||
generation and context limitations. The methodology presented
|
||
includes comprehensive PRD (Product Requirement Document) creation,
|
||
specification adherence checks, and task breakdown systems that
|
||
ensure alignment between human intent and AI execution. This guide
|
||
serves as a practical reference for developers seeking to
|
||
effectively integrate AI tools into their software development
|
||
workflow while maintaining project integrity and scalability.}
|
||
}
|
||
</code><button title="In die Zwischenablage kopieren" class="code-copy-button"><i class="bi"></i></button></pre><div class="quarto-appendix-secondary-label">Bitte zitieren Sie diese Arbeit als:</div><div id="ref-dresselhaus2025" class="csl-entry quarto-appendix-citeas" role="listitem">
|
||
Dresselhaus, Nicole. 2025. <span>“Field Report: Coding in the Age of AI
|
||
with Cursor.”</span> June 26, 2025. <a href="https://drezil.de/Writing/coding-age-ai.html">https://drezil.de/Writing/coding-age-ai.html</a>.
|
||
</div></div></section></div></main> <!-- /main -->
|
||
<script id="quarto-html-after-body" type="application/javascript">
|
||
window.document.addEventListener("DOMContentLoaded", function (event) {
|
||
// Ensure there is a toggle, if there isn't float one in the top right
|
||
if (window.document.querySelector('.quarto-color-scheme-toggle') === null) {
|
||
const a = window.document.createElement('a');
|
||
a.classList.add('top-right');
|
||
a.classList.add('quarto-color-scheme-toggle');
|
||
a.href = "";
|
||
a.onclick = function() { try { window.quartoToggleColorScheme(); } catch {} return false; };
|
||
const i = window.document.createElement("i");
|
||
i.classList.add('bi');
|
||
a.appendChild(i);
|
||
window.document.body.appendChild(a);
|
||
}
|
||
window.setColorSchemeToggle(window.hasAlternateSentinel())
|
||
const icon = "";
|
||
const anchorJS = new window.AnchorJS();
|
||
anchorJS.options = {
|
||
placement: 'right',
|
||
icon: icon
|
||
};
|
||
anchorJS.add('.anchored');
|
||
const isCodeAnnotation = (el) => {
|
||
for (const clz of el.classList) {
|
||
if (clz.startsWith('code-annotation-')) {
|
||
return true;
|
||
}
|
||
}
|
||
return false;
|
||
}
|
||
const onCopySuccess = function(e) {
|
||
// button target
|
||
const button = e.trigger;
|
||
// don't keep focus
|
||
button.blur();
|
||
// flash "checked"
|
||
button.classList.add('code-copy-button-checked');
|
||
var currentTitle = button.getAttribute("title");
|
||
button.setAttribute("title", "Kopiert");
|
||
let tooltip;
|
||
if (window.bootstrap) {
|
||
button.setAttribute("data-bs-toggle", "tooltip");
|
||
button.setAttribute("data-bs-placement", "left");
|
||
button.setAttribute("data-bs-title", "Kopiert");
|
||
tooltip = new bootstrap.Tooltip(button,
|
||
{ trigger: "manual",
|
||
customClass: "code-copy-button-tooltip",
|
||
offset: [0, -8]});
|
||
tooltip.show();
|
||
}
|
||
setTimeout(function() {
|
||
if (tooltip) {
|
||
tooltip.hide();
|
||
button.removeAttribute("data-bs-title");
|
||
button.removeAttribute("data-bs-toggle");
|
||
button.removeAttribute("data-bs-placement");
|
||
}
|
||
button.setAttribute("title", currentTitle);
|
||
button.classList.remove('code-copy-button-checked');
|
||
}, 1000);
|
||
// clear code selection
|
||
e.clearSelection();
|
||
}
|
||
const getTextToCopy = function(trigger) {
|
||
const codeEl = trigger.previousElementSibling.cloneNode(true);
|
||
for (const childEl of codeEl.children) {
|
||
if (isCodeAnnotation(childEl)) {
|
||
childEl.remove();
|
||
}
|
||
}
|
||
return codeEl.innerText;
|
||
}
|
||
const clipboard = new window.ClipboardJS('.code-copy-button:not([data-in-quarto-modal])', {
|
||
text: getTextToCopy
|
||
});
|
||
clipboard.on('success', onCopySuccess);
|
||
if (window.document.getElementById('quarto-embedded-source-code-modal')) {
|
||
const clipboardModal = new window.ClipboardJS('.code-copy-button[data-in-quarto-modal]', {
|
||
text: getTextToCopy,
|
||
container: window.document.getElementById('quarto-embedded-source-code-modal')
|
||
});
|
||
clipboardModal.on('success', onCopySuccess);
|
||
}
|
||
var localhostRegex = new RegExp(/^(?:http|https):\/\/localhost\:?[0-9]*\//);
|
||
var mailtoRegex = new RegExp(/^mailto:/);
|
||
var filterRegex = new RegExp("https:\/\/drezil\.de");
|
||
var isInternal = (href) => {
|
||
return filterRegex.test(href) || localhostRegex.test(href) || mailtoRegex.test(href);
|
||
}
|
||
// Inspect non-navigation links and adorn them if external
|
||
var links = window.document.querySelectorAll('a[href]:not(.nav-link):not(.navbar-brand):not(.toc-action):not(.sidebar-link):not(.sidebar-item-toggle):not(.pagination-link):not(.no-external):not([aria-hidden]):not(.dropdown-item):not(.quarto-navigation-tool):not(.about-link)');
|
||
for (var i=0; i<links.length; i++) {
|
||
const link = links[i];
|
||
if (!isInternal(link.href)) {
|
||
// undo the damage that might have been done by quarto-nav.js in the case of
|
||
// links that we want to consider external
|
||
if (link.dataset.originalHref !== undefined) {
|
||
link.href = link.dataset.originalHref;
|
||
}
|
||
// target, if specified
|
||
link.setAttribute("target", "_blank");
|
||
if (link.getAttribute("rel") === null) {
|
||
link.setAttribute("rel", "noopener");
|
||
}
|
||
// default icon
|
||
link.classList.add("external");
|
||
}
|
||
}
|
||
function tippyHover(el, contentFn, onTriggerFn, onUntriggerFn) {
|
||
const config = {
|
||
allowHTML: true,
|
||
maxWidth: 500,
|
||
delay: 100,
|
||
arrow: false,
|
||
appendTo: function(el) {
|
||
return el.parentElement;
|
||
},
|
||
interactive: true,
|
||
interactiveBorder: 10,
|
||
theme: 'quarto',
|
||
placement: 'bottom-start',
|
||
};
|
||
if (contentFn) {
|
||
config.content = contentFn;
|
||
}
|
||
if (onTriggerFn) {
|
||
config.onTrigger = onTriggerFn;
|
||
}
|
||
if (onUntriggerFn) {
|
||
config.onUntrigger = onUntriggerFn;
|
||
}
|
||
window.tippy(el, config);
|
||
}
|
||
const noterefs = window.document.querySelectorAll('a[role="doc-noteref"]');
|
||
for (var i=0; i<noterefs.length; i++) {
|
||
const ref = noterefs[i];
|
||
tippyHover(ref, function() {
|
||
// use id or data attribute instead here
|
||
let href = ref.getAttribute('data-footnote-href') || ref.getAttribute('href');
|
||
try { href = new URL(href).hash; } catch {}
|
||
const id = href.replace(/^#\/?/, "");
|
||
const note = window.document.getElementById(id);
|
||
if (note) {
|
||
return note.innerHTML;
|
||
} else {
|
||
return "";
|
||
}
|
||
});
|
||
}
|
||
const xrefs = window.document.querySelectorAll('a.quarto-xref');
|
||
const processXRef = (id, note) => {
|
||
// Strip column container classes
|
||
const stripColumnClz = (el) => {
|
||
el.classList.remove("page-full", "page-columns");
|
||
if (el.children) {
|
||
for (const child of el.children) {
|
||
stripColumnClz(child);
|
||
}
|
||
}
|
||
}
|
||
stripColumnClz(note)
|
||
if (id === null || id.startsWith('sec-')) {
|
||
// Special case sections, only their first couple elements
|
||
const container = document.createElement("div");
|
||
if (note.children && note.children.length > 2) {
|
||
container.appendChild(note.children[0].cloneNode(true));
|
||
for (let i = 1; i < note.children.length; i++) {
|
||
const child = note.children[i];
|
||
if (child.tagName === "P" && child.innerText === "") {
|
||
continue;
|
||
} else {
|
||
container.appendChild(child.cloneNode(true));
|
||
break;
|
||
}
|
||
}
|
||
if (window.Quarto?.typesetMath) {
|
||
window.Quarto.typesetMath(container);
|
||
}
|
||
return container.innerHTML
|
||
} else {
|
||
if (window.Quarto?.typesetMath) {
|
||
window.Quarto.typesetMath(note);
|
||
}
|
||
return note.innerHTML;
|
||
}
|
||
} else {
|
||
// Remove any anchor links if they are present
|
||
const anchorLink = note.querySelector('a.anchorjs-link');
|
||
if (anchorLink) {
|
||
anchorLink.remove();
|
||
}
|
||
if (window.Quarto?.typesetMath) {
|
||
window.Quarto.typesetMath(note);
|
||
}
|
||
if (note.classList.contains("callout")) {
|
||
return note.outerHTML;
|
||
} else {
|
||
return note.innerHTML;
|
||
}
|
||
}
|
||
}
|
||
for (var i=0; i<xrefs.length; i++) {
|
||
const xref = xrefs[i];
|
||
tippyHover(xref, undefined, function(instance) {
|
||
instance.disable();
|
||
let url = xref.getAttribute('href');
|
||
let hash = undefined;
|
||
if (url.startsWith('#')) {
|
||
hash = url;
|
||
} else {
|
||
try { hash = new URL(url).hash; } catch {}
|
||
}
|
||
if (hash) {
|
||
const id = hash.replace(/^#\/?/, "");
|
||
const note = window.document.getElementById(id);
|
||
if (note !== null) {
|
||
try {
|
||
const html = processXRef(id, note.cloneNode(true));
|
||
instance.setContent(html);
|
||
} finally {
|
||
instance.enable();
|
||
instance.show();
|
||
}
|
||
} else {
|
||
// See if we can fetch this
|
||
fetch(url.split('#')[0])
|
||
.then(res => res.text())
|
||
.then(html => {
|
||
const parser = new DOMParser();
|
||
const htmlDoc = parser.parseFromString(html, "text/html");
|
||
const note = htmlDoc.getElementById(id);
|
||
if (note !== null) {
|
||
const html = processXRef(id, note);
|
||
instance.setContent(html);
|
||
}
|
||
}).finally(() => {
|
||
instance.enable();
|
||
instance.show();
|
||
});
|
||
}
|
||
} else {
|
||
// See if we can fetch a full url (with no hash to target)
|
||
// This is a special case and we should probably do some content thinning / targeting
|
||
fetch(url)
|
||
.then(res => res.text())
|
||
.then(html => {
|
||
const parser = new DOMParser();
|
||
const htmlDoc = parser.parseFromString(html, "text/html");
|
||
const note = htmlDoc.querySelector('main.content');
|
||
if (note !== null) {
|
||
// This should only happen for chapter cross references
|
||
// (since there is no id in the URL)
|
||
// remove the first header
|
||
if (note.children.length > 0 && note.children[0].tagName === "HEADER") {
|
||
note.children[0].remove();
|
||
}
|
||
const html = processXRef(null, note);
|
||
instance.setContent(html);
|
||
}
|
||
}).finally(() => {
|
||
instance.enable();
|
||
instance.show();
|
||
});
|
||
}
|
||
}, function(instance) {
|
||
});
|
||
}
|
||
let selectedAnnoteEl;
|
||
const selectorForAnnotation = ( cell, annotation) => {
|
||
let cellAttr = 'data-code-cell="' + cell + '"';
|
||
let lineAttr = 'data-code-annotation="' + annotation + '"';
|
||
const selector = 'span[' + cellAttr + '][' + lineAttr + ']';
|
||
return selector;
|
||
}
|
||
const selectCodeLines = (annoteEl) => {
|
||
const doc = window.document;
|
||
const targetCell = annoteEl.getAttribute("data-target-cell");
|
||
const targetAnnotation = annoteEl.getAttribute("data-target-annotation");
|
||
const annoteSpan = window.document.querySelector(selectorForAnnotation(targetCell, targetAnnotation));
|
||
const lines = annoteSpan.getAttribute("data-code-lines").split(",");
|
||
const lineIds = lines.map((line) => {
|
||
return targetCell + "-" + line;
|
||
})
|
||
let top = null;
|
||
let height = null;
|
||
let parent = null;
|
||
if (lineIds.length > 0) {
|
||
//compute the position of the single el (top and bottom and make a div)
|
||
const el = window.document.getElementById(lineIds[0]);
|
||
top = el.offsetTop;
|
||
height = el.offsetHeight;
|
||
parent = el.parentElement.parentElement;
|
||
if (lineIds.length > 1) {
|
||
const lastEl = window.document.getElementById(lineIds[lineIds.length - 1]);
|
||
const bottom = lastEl.offsetTop + lastEl.offsetHeight;
|
||
height = bottom - top;
|
||
}
|
||
if (top !== null && height !== null && parent !== null) {
|
||
// cook up a div (if necessary) and position it
|
||
let div = window.document.getElementById("code-annotation-line-highlight");
|
||
if (div === null) {
|
||
div = window.document.createElement("div");
|
||
div.setAttribute("id", "code-annotation-line-highlight");
|
||
div.style.position = 'absolute';
|
||
parent.appendChild(div);
|
||
}
|
||
div.style.top = top - 2 + "px";
|
||
div.style.height = height + 4 + "px";
|
||
div.style.left = 0;
|
||
let gutterDiv = window.document.getElementById("code-annotation-line-highlight-gutter");
|
||
if (gutterDiv === null) {
|
||
gutterDiv = window.document.createElement("div");
|
||
gutterDiv.setAttribute("id", "code-annotation-line-highlight-gutter");
|
||
gutterDiv.style.position = 'absolute';
|
||
const codeCell = window.document.getElementById(targetCell);
|
||
const gutter = codeCell.querySelector('.code-annotation-gutter');
|
||
gutter.appendChild(gutterDiv);
|
||
}
|
||
gutterDiv.style.top = top - 2 + "px";
|
||
gutterDiv.style.height = height + 4 + "px";
|
||
}
|
||
selectedAnnoteEl = annoteEl;
|
||
}
|
||
};
|
||
const unselectCodeLines = () => {
|
||
const elementsIds = ["code-annotation-line-highlight", "code-annotation-line-highlight-gutter"];
|
||
elementsIds.forEach((elId) => {
|
||
const div = window.document.getElementById(elId);
|
||
if (div) {
|
||
div.remove();
|
||
}
|
||
});
|
||
selectedAnnoteEl = undefined;
|
||
};
|
||
// Handle positioning of the toggle
|
||
window.addEventListener(
|
||
"resize",
|
||
throttle(() => {
|
||
elRect = undefined;
|
||
if (selectedAnnoteEl) {
|
||
selectCodeLines(selectedAnnoteEl);
|
||
}
|
||
}, 10)
|
||
);
|
||
function throttle(fn, ms) {
|
||
let throttle = false;
|
||
let timer;
|
||
return (...args) => {
|
||
if(!throttle) { // first call gets through
|
||
fn.apply(this, args);
|
||
throttle = true;
|
||
} else { // all the others get throttled
|
||
if(timer) clearTimeout(timer); // cancel #2
|
||
timer = setTimeout(() => {
|
||
fn.apply(this, args);
|
||
timer = throttle = false;
|
||
}, ms);
|
||
}
|
||
};
|
||
}
|
||
// Attach click handler to the DT
|
||
const annoteDls = window.document.querySelectorAll('dt[data-target-cell]');
|
||
for (const annoteDlNode of annoteDls) {
|
||
annoteDlNode.addEventListener('click', (event) => {
|
||
const clickedEl = event.target;
|
||
if (clickedEl !== selectedAnnoteEl) {
|
||
unselectCodeLines();
|
||
const activeEl = window.document.querySelector('dt[data-target-cell].code-annotation-active');
|
||
if (activeEl) {
|
||
activeEl.classList.remove('code-annotation-active');
|
||
}
|
||
selectCodeLines(clickedEl);
|
||
clickedEl.classList.add('code-annotation-active');
|
||
} else {
|
||
// Unselect the line
|
||
unselectCodeLines();
|
||
clickedEl.classList.remove('code-annotation-active');
|
||
}
|
||
});
|
||
}
|
||
const findCites = (el) => {
|
||
const parentEl = el.parentElement;
|
||
if (parentEl) {
|
||
const cites = parentEl.dataset.cites;
|
||
if (cites) {
|
||
return {
|
||
el,
|
||
cites: cites.split(' ')
|
||
};
|
||
} else {
|
||
return findCites(el.parentElement)
|
||
}
|
||
} else {
|
||
return undefined;
|
||
}
|
||
};
|
||
var bibliorefs = window.document.querySelectorAll('a[role="doc-biblioref"]');
|
||
for (var i=0; i<bibliorefs.length; i++) {
|
||
const ref = bibliorefs[i];
|
||
const citeInfo = findCites(ref);
|
||
if (citeInfo) {
|
||
tippyHover(citeInfo.el, function() {
|
||
var popup = window.document.createElement('div');
|
||
citeInfo.cites.forEach(function(cite) {
|
||
var citeDiv = window.document.createElement('div');
|
||
citeDiv.classList.add('hanging-indent');
|
||
citeDiv.classList.add('csl-entry');
|
||
var biblioDiv = window.document.getElementById('ref-' + cite);
|
||
if (biblioDiv) {
|
||
citeDiv.innerHTML = biblioDiv.innerHTML;
|
||
}
|
||
popup.appendChild(citeDiv);
|
||
});
|
||
return popup.innerHTML;
|
||
});
|
||
}
|
||
}
|
||
});
|
||
</script>
|
||
</div> <!-- /content -->
|
||
<script>var lightboxQuarto = GLightbox({"closeEffect":"zoom","descPosition":"bottom","loop":false,"openEffect":"zoom","selector":".lightbox"});
|
||
(function() {
|
||
let previousOnload = window.onload;
|
||
window.onload = () => {
|
||
if (previousOnload) {
|
||
previousOnload();
|
||
}
|
||
lightboxQuarto.on('slide_before_load', (data) => {
|
||
const { slideIndex, slideNode, slideConfig, player, trigger } = data;
|
||
const href = trigger.getAttribute('href');
|
||
if (href !== null) {
|
||
const imgEl = window.document.querySelector(`a[href="${href}"] img`);
|
||
if (imgEl !== null) {
|
||
const srcAttr = imgEl.getAttribute("src");
|
||
if (srcAttr && srcAttr.startsWith("data:")) {
|
||
slideConfig.href = srcAttr;
|
||
}
|
||
}
|
||
}
|
||
});
|
||
|
||
lightboxQuarto.on('slide_after_load', (data) => {
|
||
const { slideIndex, slideNode, slideConfig, player, trigger } = data;
|
||
if (window.Quarto?.typesetMath) {
|
||
window.Quarto.typesetMath(slideNode);
|
||
}
|
||
});
|
||
|
||
};
|
||
|
||
})();
|
||
</script>
|
||
|
||
|
||
|
||
|
||
</body></html> |