88 lines
3.2 KiB
Org Mode
88 lines
3.2 KiB
Org Mode
* sighelp.go : GPT-Assistable Semantic Outline
|
|
|
|
This file provides *non-functional symbolic structure* for the corresponding =.go= file (e.g. =init.go=), optimized for:
|
|
|
|
- GPT parsing and assistance
|
|
- IDE symbol navigation (LSP)
|
|
- Type-checking to detect drift
|
|
- Readable overview for human developers
|
|
|
|
Each =sighelp_XXX()= function:
|
|
|
|
- Mirrors a real function (e.g. =InitRabbitMQ=)
|
|
- Calls it with placeholder arguments
|
|
- Discards the result to avoid side effects
|
|
- Includes structured GPT-readable comments in the form =// gpt:<tag>: …=
|
|
|
|
This allows both humans and GPT tools to:
|
|
|
|
- See what functions exist and what they do
|
|
- Understand return types and call relations
|
|
- Navigate codebases via structure, not prose
|
|
|
|
**Example**
|
|
|
|
#+BEGIN_SRC go
|
|
// gpt:flowinfo: InitMinIOArtifactStore returns a store configured via env vars
|
|
func sighelp_InitMinIOArtifactStore() {
|
|
var s artifactstore.Store
|
|
var err error
|
|
s, err = InitMinIOArtifactStore()
|
|
_ = s
|
|
_ = err
|
|
}
|
|
#+END_SRC
|
|
|
|
**Style Guidelines**
|
|
|
|
- Always use valid, compilable Go.
|
|
- Maintain one =sighelp_= per actual function.
|
|
- Add =// gpt:= comments to express intent or relationships.
|
|
- Avoid runtime logic — this file is for *structure*, not execution.
|
|
|
|
* GPT-Assisted Spec → Code Change Workflow
|
|
|
|
To reduce time spent mapping high-level spec changes to actual code edits, we use this workflow to integrate GPT into the loop. This allows structured delegation of search, mapping, and edit proposal.
|
|
|
|
**Flow**
|
|
|
|
1. You declare a spec change as a structured Org block (see below).
|
|
2. GPT uses =sighelp.go= (and optionally the real code) to:
|
|
- Identify affected functions
|
|
- Propose an edit plan
|
|
- Track and validate type-level constraints
|
|
3. You confirm the plan or adjust scope.
|
|
4. GPT writes candidate diffs or summaries for manual patching.
|
|
|
|
**Example Change Request**
|
|
|
|
#+BEGIN_SRC org
|
|
,* Change: Make artifact store initialization async with retry
|
|
,* Affects: InitMinIOArtifactStore, InitMinIOCodeQLDatabaseStore
|
|
,* Required: non-blocking behavior, robust to transient failures
|
|
,* Notes: Must be compatible with sighelp stubs and InitX signatures
|
|
#+END_SRC
|
|
|
|
**GPT Responsibilities**
|
|
|
|
- Match affected symbols from =sighelp_XXX()= stubs
|
|
- Generate patch plan as Org list:
|
|
#+BEGIN_SRC org
|
|
,* deploy/init.go
|
|
- InitMinIOArtifactStore: wrap NewMinIOArtifactStore in goroutine, add retry
|
|
- InitMinIOCodeQLDatabaseStore: apply same pattern
|
|
#+END_SRC
|
|
- Output scoped diffs, patch instructions, or replacement code
|
|
|
|
**Optional Enhancements**
|
|
|
|
- GPT can update =sighelp.go= alongside implementation changes
|
|
- You may keep =change.org= files in the repo to track historical refactor plans
|
|
- Each change block can include tags like =:spec:async:init:= for search
|
|
|
|
* Summary
|
|
|
|
This structure treats GPT as a symbolic reasoning assistant that uses =sighelp.go= as its internal call graph. It allows high-level human changes to be mapped, tracked, and diffed without manual bottom-up spelunking.
|
|
|
|
This flow is especially effective when multiple entry points share structural patterns (e.g. InitXXX for services).
|