feedback
Use when implementation, review, security, scalability, or incident work reveals that an upstream .forge/ artifact is wrong, when a contract is missing an operation, when an ADR is being contradicted
SKILL.mdskills/feedback/SKILL.md
GitHubFeedback (reverse cascade)
Overview
Capture a finding from any downstream stage into a structured .forge/feedback/<timestamp>-<source>.md entry that targets one upstream artifact. The entry stays as status: PENDING until the upstream skill re-runs and addresses it. forge-sync flags the target artifact as FEEDBACK_PENDING until the entry is resolved.
This is the only sanctioned reverse-cascade primitive. The forward chain (prd → arch → tasks → code) flows one direction; backward propagation happens through these entries, not by directly editing upstream artifacts mid-stream.
When to Use
- During
/buildyou discover the relevant contract is missing an operation or has the wrong shape - During
/reviewyou find an architectural flaw that wasn't visible at design time - During
/secureor/scaleyou produce a recommendation that implies architecture changes (add a WAF, change a data store, add a gateway) - During an incident you discover an error path the error-handling spec didn't cover
- After a sprint, you realize ≥3 tasks split mid-flight — the plan needs an update before the next sprint
When NOT to Use
- The fix is fully contained inside the current stage (don't escalate every implementation detail)
- You have permission to edit the upstream artifact directly and want to do so — then just edit it;
forge-syncwill flag downstream as STALE - The finding is a question, not a recommended change — discuss with the user first; file the entry once a recommendation crystallizes
- The target artifact doesn't exist (
.forge/security.mdnot yet generated) — run the source skill instead
Common Rationalizations
| Thought | Reality |
|---|---|
| "I'll just edit the contract inline" | Then the chain has no record of WHY it changed. Future readers see a contract that contradicts the PRD with no explanation. |
| "Filing a feedback entry is overhead — I'll fix it later" | "Later" means the finding is forgotten by the time the upstream skill re-runs. The entry is the memory. |
| "The upstream skill will figure it out when it re-runs" | The upstream skill regenerates from its inputs, not from the downstream's discovery. Without a feedback entry, the regenerated artifact has the same flaw. |
| "This is too small for a feedback entry" | Three small findings ignored = one big surprise at /ship. |
| "I'll just tell the user verbally" | Verbal findings evaporate. The entry survives session boundaries. |
Red Flags
- Editing
.forge/contracts/<X>.mddirectly during/buildinstead of filing a feedback entry - A sprint ends with no
.forge/feedback/entries despite ≥3 tasks havingnotespopulated forge-syncreportsFEEDBACK_PENDINGon artifacts that are about to be re-generated, but the regenerating skill doesn't read.forge/feedback/- A
.forge/feedback/*.mdfile exists withstatus: PENDINGfor more than two sprints — either resolve it or mark itDEFERREDwith a reason
Core Process
Step 1: Identify source, target, and finding
- Source stage: which skill or activity discovered the issue (
build,review,secure,scale,incident,manual) - Source context: task ID, commit, PR, incident ID, or "manual" if ad-hoc
- Target artifact: which
.forge/file needs revision. Must exist on disk. If multiple files need revision, file separate entries. - Finding: what was discovered (1-3 sentences, specific)
- Recommended change: what should change in the target artifact (specific enough that re-running the source skill can apply it)
Step 2: Decide severity
Choose one:
- NEEDS_REVIEW — finding requires a human decision; auto-cascade not safe (e.g., "add WAF" — the human decides whether to absorb the change in architecture or defer)
- FEEDBACK_PENDING — recommended change is mechanical; the upstream skill can apply it on re-run (e.g., "add
refundendpoint to PaymentService contract")
Both states block /ship. Only NEEDS_REVIEW blocks /build if it touches the in-flight task's contract.
Step 3: Write the entry
Path: .forge/feedback/<ISO8601-UTC-with-dashes>-<source>.md — e.g., .forge/feedback/2026-05-14T103000Z-build.md.
<!-- forge:meta
generated_by: feedback
generated_at: 2026-05-14T10:30:00Z
depends_on: [.forge/contracts/payment-service.md]
generated_from:
.forge/contracts/payment-service.md: <target's content_hash AT filing time>
content_hash: <first 8 chars of sha256 over this entry's body>
-->
# Feedback: <short title>
- **Source stage:** build (incremental-implementation, task T-042)
- **Source context:** commit pending; branch task/T-042-refund-flow
- **Target artifact:** .forge/contracts/payment-service.md
- **Severity:** FEEDBACK_PENDING
- **Status:** PENDING
- **Filed at:** 2026-05-14T10:30:00Z
- **Resolved at:** —
## Finding
While implementing the refund flow, the PaymentService contract has no `refund(transactionId, amount)` operation. The PRD's "User can refund failed transactions within 30 days" story can't be satisfied without it.
## Recommended change
Add to `Provides` in `.forge/contracts/payment-service.md`:
refund(input: RefundInput): RefundOutput | RefundError
with:
- `RefundInput = { transactionId: string, amount?: number, idempotencyKey: string }`
- `RefundOutput = { refundId, refundedAt, amount }`
- `RefundError` cases: `TransactionNotFound`, `RefundWindowExpired`, `AlreadyRefunded`, `PartialRefundNotAllowed`
Idempotency-Key required per `api-design.md` mutation policy.
## Cascade
- Re-run `/architect` (or edit the contract directly) to address this entry.
- After contract update, re-run `/plan` if the refund story needs new tasks beyond T-042.
- `forge-sync` will mark this entry `RESOLVED` once the target artifact's `generated_at` advances past this entry's `generated_at` AND the recommended operation appears in the target.
depends_on is the target_artifact (single-element list) — that's what forge-sync reads to identify what's being annotated.
Step 4: Confirm with user
Print the entry path and a one-line summary:
Filed
.forge/feedback/2026-05-14T103000Z-build.md— target.forge/contracts/payment-service.md, severity FEEDBACK_PENDING. Run/syncto see chain impact.
Do not modify the target artifact in this skill. The skill is write-only into .forge/feedback/.
Step 5: Tracking resolution
The feedback skill itself does not resolve entries. Resolution happens when the targeted upstream skill re-runs:
- The upstream skill (e.g.,
architecture-and-contracts) reads all.forge/feedback/*.mdentries wheretarget_artifactmatches an output it owns ANDstatus: PENDING. - It addresses each in its regeneration.
- After writing, it updates each addressed entry:
status: RESOLVED,resolved_at: <now UTC>,resolved_by: <commit or "manual">. forge-syncconfirms the resolution by checking that the target artifact's content reflects the recommended change.
Entries can also be marked DEFERRED (with a reason in the body) when the team decides not to act — the entry stays in the directory as historical record.
Verification
-
.forge/feedback/<timestamp>-<source>.mdwritten - Filename timestamp is UTC with Z; format
YYYY-MM-DDTHHMMSSZ-<source>.md -
forge:metaheader hasdepends_on: [<single target artifact path>] - Severity is one of
FEEDBACK_PENDINGorNEEDS_REVIEW - Status is
PENDINGat filing time - Recommended change is specific (operation name, type names, error cases — not "make it better")
- Cascade section names which upstream skill should re-run
- No upstream artifact was directly edited by this skill